Po wdrożeniu nowej wersji endpoint zwraca 500, a komunikat w przeglądarce nie mówi, czy winny jest kod, baza czy usługa pośrednia. Internal Server Error oznacza, że serwer nie obsłużył żądania z powodu nieoczekiwanej sytuacji, ale sam kod odpowiedzi nie wskazuje jeszcze miejsca awarii.
Sam kod 500 nie wskaże winnej warstwy
- HTTP 500 to ogólna odpowiedź serwera, a nie diagnoza konkretnego błędu.
- Zakres awarii zawęzisz, sprawdzając, czy problem dotyczy jednego endpointu, regionu, klienta czy wszystkich żądań.
- Logi i trace ID połączą odpowiedź widoczną dla klienta ze zdarzeniem w aplikacji lub infrastrukturze.
- Ponowienie żądania może pomóc przy krótkim zakłóceniu, ale przy operacji zapisującej dane grozi jej wykonaniem dwa razy.
HTTP 500 opisuje skutek, nie przyczynę
Specyfikacja RFC 9110 definiuje ten status jako sygnał, że serwer napotkał nieoczekiwany warunek i nie mógł zrealizować żądania. W praktyce odpowiedź może powstać w aplikacji, serwerze WWW albo warstwie pośredniczącej, więc treść komunikatu sama w sobie nie ujawnia, która z nich zawiodła.
To rozróżnienie chroni przed częstym skrótem myślowym: „500 oznacza błąd aplikacji”. Uważam, że lepiej traktować ten kod jako punkt wejścia do diagnostyki, a nie gotowe rozpoznanie. Szczególnie że podobne problemy w infrastrukturze dostają inne kody.
Porównaj 500 z 502, 503 i 504, zanim zmienisz kod
Różnica między tymi odpowiedziami wskazuje, gdzie szukać pierwszego tropu. 500 mówi ogólnie o nieoczekiwanym błędzie po stronie serwera; pozostałe kody precyzują problemy związane z pośrednikiem, dostępnością lub czasem odpowiedzi.
| Odpowiedź | Co sygnalizuje | Pierwszy trop |
|---|---|---|
| 500 Internal Server Error | Serwer napotkał nieoczekiwany warunek. | Wyjątek aplikacji, konfiguracja, zależność albo wyczerpany zasób. |
| 502 Bad Gateway | Serwer działający jako brama lub proxy dostał nieprawidłową odpowiedź od serwera nadrzędnego. | Połączenie i odpowiedź backendu widziane z warstwy proxy. |
| 503 Service Unavailable | Usługa nie może teraz obsłużyć żądania. | Przeciążenie, niedostępna instancja lub zaplanowane wyłączenie. |
| 504 Gateway Timeout | Brama nie otrzymała odpowiedzi na czas. | Opóźniony backend albo zależność, która nie odpowiada w limicie. |
To wskazówki, nie niepodważalne etykiety: aplikacja może zwrócić 500 także wtedy, gdy problem zaczął się w zależności, a konfiguracja proxy może zmienić widoczny status. Sprawdź więc odpowiedź z każdej warstwy, zamiast opierać diagnozę wyłącznie na kodzie widocznym w przeglądarce.
Najpierw ustal, czy awaria jest lokalna, czy szeroka
Jeden błąd po wdrożeniu i seria błędów w całym regionie to dwa różne scenariusze. Zanim zaczniesz edytować konfigurację, zestaw czas wystąpienia odpowiedzi z wdrożeniami, metrykami i logami; taki prosty przekrój często ogranicza liczbę możliwych przyczyn.
| Sytuacja | Prawdopodobny trop | Co zrobić |
|---|---|---|
| 500 pojawia się wyłącznie na jednym endpointcie. | Błąd ścieżki kodu, walidacji danych albo jej zależności. | Porównaj logi żądań z udanymi wywołaniami tego samego endpointu. |
| Błędy zaczynają się tuż po wdrożeniu. | Regresja, migracja schematu lub niezgodna konfiguracja. | Sprawdź różnice między wersjami i rozważ rollback, jeśli awaria obejmuje krytyczny przepływ. |
| Wiele endpointów zawodzi jednocześnie. | Wspólna zależność, pula połączeń, pamięć albo problem infrastruktury. | Sprawdź metryki zasobów i statusy zależności, zanim zmienisz kod aplikacji. |
| Błąd dotyczy tylko części żądań lub jednej instancji. | Nierówny ruch, wadliwy węzeł albo różnice w konfiguracji. | Porównaj instancje, strefy i identyfikatory żądań; sprawdź, czy ruch trafia nierówno. |
Jeśli wpis w logu aplikacji nie odpowiada błędowi widocznemu na brzegu systemu, sprawdź logi reverse proxy, load balancera i bramy API. Brak wyjątku w aplikacji nie dowodzi, że żądanie przeszło przez nią bez problemu.
Trace ID skraca drogę od alarmu do przyczyny
Komunikat dla użytkownika powinien być oszczędny, ale log wewnętrzny musi zawierać dane pozwalające odtworzyć przebieg żądania. Generuj lub przekazuj identyfikator korelacyjny przez kolejne usługi, a następnie zapisuj go przy błędzie razem z nazwą endpointu, wersją aplikacji, instancją i czasem.
Przykładowo: po wdrożeniu rośnie liczba odpowiedzi 500 na jednym endpointcie, lecz wykres dostępności całej usługi nadal wygląda dobrze. Filtr po trace ID ujawnia, że błędy dotyczą wywołań zależności, podczas gdy pozostałe ścieżki działają. W takim przypadku sprawdź limit czasu, obsługę wyjątku i zmianę kontraktu integracji, zamiast restartować wszystkie instancje.
Nie zapisuj w odpowiedzi dla klienta stack trace, sekretów ani szczegółów infrastruktury. Pełne szczegóły zostaw w zabezpieczonych logach; na zewnątrz zwróć krótki komunikat i identyfikator, który można przekazać zespołowi wsparcia.
Ponawiaj bezpiecznie, bo retry może powielić zapis
Automatyczna ponowna próba bywa rozsądna przy przejściowym problemie, ale nie rozwiąże trwałego wyjątku ani błędnej konfiguracji. Dokumentacja Amazon DynamoDB opisuje, że w tej usłudze błędy 500 mogą wynikać między innymi z przejściowych problemów sieciowych lub infrastrukturalnych; to przykład specyficzny dla DynamoDB, a nie obietnica, że każdy błąd 500 zniknie po ponowieniu.
Przy żądaniu odczytu ponowienie często jest bezpieczniejsze. Przy płatności, utworzeniu zamówienia albo innym zapisie klient może nie wiedzieć, czy serwer zdążył wykonać operację przed błędem. Stosuj retry z ograniczoną liczbą prób i narastającym opóźnieniem, a operacje, które mogą zostać powtórzone, zabezpieczaj kluczem idempotencji, czyli identyfikatorem pozwalającym rozpoznać ponowne wysłanie tej samej operacji.
Gdy alert dotyczy krytycznego przepływu, a błędy zaczęły się po zmianie, najpierw przywróć sprawne działanie, na przykład przez rollback, jeśli potwierdzają to dane. Potem odtwórz zdarzenie na podstawie logów i popraw przyczynę; samo maskowanie 500 kolejną próbą może zamienić awarię w serię duplikatów.
Zamień pojedyncze 500 w użyteczny sygnał
Pojedynczy status nie wyjaśni awarii, ale dobrze zaprojektowany monitoring może szybko pokazać jej zasięg i moment początku. Alertuj na odsetek błędów w danym endpointcie, nie tylko na surową liczbę odpowiedzi, i zestawiaj go z opóźnieniami oraz wersją wdrożenia.
Gdy pojawi się następny 500, zacznij od pytania, gdzie odpowiedź powstała i które żądania obejmuje. To prowadzi do logów, trace ID i właściwej warstwy systemu, zamiast do przypadkowych restartów.
