Błąd 504 pojawia się wtedy, gdy bramka, proxy albo load balancer czekają zbyt długo na odpowiedź z serwera źródłowego. W praktyce to jeden z tych komunikatów, które wyglądają groźnie, ale zwykle mówią bardzo konkretnie, gdzie przerwał się łańcuch żądań. W tym tekście rozkładam na czynniki pierwsze 504 error: wyjaśniam, co oznacza, skąd się bierze, jak odróżnić problem po stronie użytkownika od awarii serwisu i co zrobić, żeby go szybko usunąć.
Najkrócej to opóźnienie między bramką a serwerem źródłowym
- 504 oznacza, że pośrednia warstwa HTTP nie dostała odpowiedzi na czas od serwera upstream.
- Najczęściej winny jest wolny backend, przeciążona baza danych, zewnętrzne API albo zbyt krótki timeout po stronie proxy.
- To zwykle nie jest problem samej przeglądarki, choć VPN, proxy i DNS potrafią go imitować.
- Użytkownik może odświeżyć stronę, sprawdzić sieć i wyłączyć niestandardowe pośredniki, ale administrator musi zajrzeć do logów, czasów odpowiedzi i zależności aplikacji.
- Podnoszenie timeoutu bez skrócenia zapytań tylko maskuje problem, zamiast go naprawić.
- 504 różni się od 502 i 503, więc warto umieć rozpoznać, która warstwa faktycznie zawiodła.
Czym jest błąd 504 i co właściwie oznacza
W uproszczeniu chodzi o sytuację, w której serwer pośredniczący nie doczekał się odpowiedzi z serwera końcowego. Tak działa wiele współczesnych architektur: użytkownik nie łączy się bezpośrednio z jedną maszyną, tylko z warstwą pośrednią, która przekazuje żądanie dalej. Reverse proxy to właśnie taki pośrednik, a load balancer rozdziela ruch między kilka instancji aplikacji, żeby system nie zapychał się w jednym miejscu.
Jak opisuje RFC 9110, ten kod oznacza, że serwer działający jako gateway albo proxy nie dostał terminowej odpowiedzi od upstreamu, czyli serwera „za nim”, potrzebnego do dokończenia żądania. I to jest ważne: 504 nie mówi, że strona nie istnieje, tylko że odpowiedź przyszła za późno albo wcale nie przyszła w dopuszczalnym czasie. MDN opisuje to podobnie i podkreśla, że przyczyna leży zwykle w warstwie serwera, nie w samej przeglądarce.
Jeżeli ten komunikat pojawia się sporadycznie, problem bywa chwilowy. Jeżeli wraca regularnie, zwykle oznacza to, że któryś element architektury pracuje zbyt wolno, zbyt długo blokuje zasoby albo ma ustawiony timeout poniżej realnego czasu odpowiedzi. Kiedy rozumie się ten mechanizm, łatwiej odróżnić objaw od prawdziwej przyczyny, a to prowadzi do sedna następnej sekcji.
Dlaczego pojawia się timeout po stronie serwera
Najczęstszy scenariusz jest dość prozaiczny: backend nie zdążył odpowiedzieć, więc warstwa pośrednia zamknęła połączenie. Cloudflare opisuje podobne przypadki wprost, zaznaczając, że 502 i 504 zwykle wiążą się z problemem kontaktu z originem, czyli głównym serwerem obsługującym treść. W praktyce źródłem opóźnienia może być kilka miejsc naraz, dlatego patrzę na nie warstwowo, a nie „na oko”.
| Przyczyna | Co się dzieje | Gdzie zwykle szukać problemu |
|---|---|---|
| Wolna baza danych | Zapytanie czeka na wynik zbyt długo, bo są blokady, brak indeksu albo za ciężki filtr | SQL, indeksy, transakcje, locki |
| Zewnętrzne API | Aplikacja zatrzymuje się na integracji, która nie odpowiada na czas | Płatności, mapy, logowanie, webhooki |
| Przeciążony backend | CPU, RAM albo I/O są blisko granicy i żądania ustawiają się w kolejce | Serwer aplikacji, workerzy, autoskalowanie |
| Zbyt krótki timeout pośrednika | Serwer działa, ale bramka ucina połączenie wcześniej, niż aplikacja zdąży odpowiedzieć | Reverse proxy, CDN, load balancer |
| Błąd w logice aplikacji | Endpoint wisi na operacji, która nigdy nie dochodzi do końca albo robi to za długo | Kod aplikacji, kolejki zadań, zależności |
W środowiskach opartych na PHP często widać to między Nginx a PHP-FPM. PHP-FPM to menedżer procesów obsługujących skrypty PHP, więc jeśli kolejka się zapycha, Nginx czeka i w końcu zwraca 504. Podobnie działa to w serwisach opartych na Node.js, Pythonie czy Java Springu: sama technologia nie ma znaczenia, jeśli jedna warstwa nie nadąża za ruchem albo za ciężarem żądania. Kiedy już wiem, gdzie mogą leżeć źródła opóźnienia, przechodzę do szybkiej diagnostyki, bo ten sam komunikat może mieć zupełnie różne przyczyny.
Jak odróżnić awarię serwisu od problemu po swojej stronie
Tu przydaje się proste myślenie testowe. Jeśli problem dotyczy tylko jednej witryny, a pozostałe strony działają normalnie, zwykle bardziej podejrzany jest serwis. Jeśli za to kłopoty pojawiają się na wielu stronach, tylko na jednej sieci albo po włączeniu VPN, trzeba brać pod uwagę DNS, proxy, firewall albo samą trasę sieciową.
| Obserwacja | Co to sugeruje |
|---|---|
| Błąd występuje tylko na jednej stronie | Problem po stronie serwisu, backendu albo jego pośredników |
| Strona działa na telefonie, ale nie działa na firmowym Wi-Fi | Sieć, DNS, filtr bezpieczeństwa albo proxy po Twojej stronie |
| Komunikat pojawia się po dokładnie podobnym czasie, np. po kilkudziesięciu sekundach | Timeout ustawiony w bramce, proxy albo load balancerze |
| Problem dotyczy tylko ciężkich akcji, takich jak eksport, raport lub duży upload | Zbyt długa operacja w aplikacji lub zbyt mało wydajny backend |
| Po chwili odświeżenia wszystko wraca do normy | Chwilowe przeciążenie albo krótka niedostępność upstreamu |
Jeśli mam tylko jedną wskazówkę dla użytkownika końcowego, to tę: sprawdź działanie strony na innej sieci i bez VPN. To szybki test, który bardzo często oddziela problem lokalny od awarii po stronie serwisu. Gdy ten krok nie daje odpowiedzi, warto przejść do konkretnych działań naprawczych zamiast bez końca odświeżać kartę.
Co zrobić od razu, gdy zobaczysz ten komunikat
Jako zwykły użytkownik nie naprawisz backendu, ale możesz ograniczyć straty czasu i zebrać sensowne informacje dla supportu. Ja zacząłbym od najprostszych ruchów, bo właśnie one najczęściej pokazują, czy sprawa jest chwilowa, czy systemowa.
- Odśwież stronę po krótkiej przerwie, najlepiej po 30-60 sekundach, zamiast spamować F5 co kilka sekund.
- Sprawdź, czy problem dotyczy tylko jednej zakładki, jednego formularza albo jednego endpointu.
- Wyłącz VPN, prywatny proxy i nietypowe rozszerzenia sieciowe, które mogą mieszać w ruchu HTTP.
- Przetestuj stronę na innej sieci, na przykład na danych komórkowych.
- Jeśli to ważny proces biznesowy, zapisz godzinę błędu, adres podstrony i informację, czy problem dotyczył całej witryny, czy tylko jednej operacji.
- Sprawdź status page serwisu, jeśli taka istnieje, bo to najszybciej pokazuje, czy awaria jest szeroka.
W praktyce nie warto bezrefleksyjnie odświeżać strony dziesiątki razy. Przy przeciążonym systemie każdy dodatkowy request dorzuca obciążenie, a przy długich operacjach i tak niczego nie przyspiesza. Jeśli to jednak Twoja strona albo Twoja aplikacja, potrzebujesz już bardziej technicznego podejścia, bo samo „spróbuj ponownie później” nie usuwa przyczyny.
Jak naprawić błąd 504 na stronie lub w aplikacji
Tu zaczyna się część, którą najbardziej cenię w pracy z incydentami: najpierw lokalizacja wąskiego gardła, potem korekta. Najgorszy nawyk to podnoszenie timeoutów na ślepo, bo to zwykle tylko przesuwa objaw o kolejne kilkanaście lub kilkadziesiąt sekund. Jeśli backend odpowiada zbyt wolno, trzeba ustalić, dlaczego tak się dzieje.
Sprawdź, gdzie kończy się łańcuch żądania
Zaczynam od logów reverse proxy, aplikacji i bazy danych. Reverse proxy to warstwa, która przyjmuje ruch z internetu i przekazuje go dalej, więc właśnie tam najczęściej widać, czy timeout powstał na styku z upstreamem. W systemach z load balancerem sprawdzam też health checki, bo błędnie skonfigurowany test zdrowia potrafi odcinać instancję mimo tego, że sama aplikacja jeszcze działa.
Skróć najwolniejsze operacje
Jeśli timeout pojawia się przy raportach, eksportach albo dużych filtrach, nie próbuję udawać, że synchronizacja „jakoś się obroni”. Lepiej przenieść ciężką pracę do kolejki zadań i zwrócić klientowi odpowiedź typu 202 Accepted, a wynik udostępnić później. To bardziej stabilne niż trzymanie połączenia przez pół minuty lub dłużej. W przypadku bazy danych zwykle szukam brakujących indeksów, nadmiarowych joinów i zbyt długich transakcji.
Przeczytaj również: Plik DWG - Otwórz bez AutoCAD, zrozum i uniknij błędów
Ustaw timeouty z zapasem, ale nie zamiast optymalizacji
Timeout powinien odzwierciedlać realne możliwości systemu, a nie maskować jego słabości. Jeśli warstwa pośrednia odcina po 60 sekundach, a aplikacja regularnie potrzebuje 55, to nie masz jeszcze stabilnego rozwiązania, tylko wrażenie, że „prawie działa”. Ja wolę, gdy aplikacja kończy typowe żądania z dużym zapasem względem limitu, a nie balansuje na krawędzi.
- Włącz cache dla treści, które często się powtarzają.
- Rozbij duże odpowiedzi na strony lub paczki danych.
- Ogranicz długie transakcje i blokady w bazie.
- Dodaj retry z backoffem dla zewnętrznych API, ale nie wykonuj ich bez końca.
- Monitoruj czasy odpowiedzi zarówno dla całej aplikacji, jak i dla pojedynczych endpointów.
W dobrze prowadzonym serwisie taki przegląd szybko pokazuje, czy problem jest w kodzie, infrastrukturze, czy w zależnościach zewnętrznych. To prowadzi do bardzo ważnego rozróżnienia między kodami 502, 503 i 504, które użytkownicy często wrzucają do jednego worka.
Czym 504 różni się od 502 i 503
Te trzy kody są podobne tylko na pierwszy rzut oka. Dla osoby zarządzającej serwisem różnica jest praktyczna, bo mówi, który element łańcucha zawiódł i jakiej naprawy szukać najpierw. 502 zwykle dotyczy złej odpowiedzi od upstreamu, 503 to niedostępność usługi, a 504 oznacza, że odpowiedź nie przyszła na czas.
| Kod | Znaczenie | Co zwykle dzieje się w praktyce | Pierwszy krok |
|---|---|---|---|
| 502 Bad Gateway | Bramka dostała nieprawidłową odpowiedź od serwera za sobą | Upstream zwrócił coś błędnego, niepełnego albo niezgodnego | Sprawdź aplikację i komunikację między warstwami |
| 503 Service Unavailable | Usługa jest chwilowo niedostępna | Serwis jest przeciążony, w maintenance albo celowo odrzuca ruch | Sprawdź stan usługi, limity zasobów i tryb utrzymaniowy |
| 504 Gateway Timeout | Pośrednik nie dostał odpowiedzi na czas | Backend działa za wolno, wisi na zależności albo timeout jest zbyt krótki | Znajdź warstwę, która opóźnia odpowiedź |
Ta różnica naprawdę ma znaczenie, bo 503 często wymaga odciążenia lub chwilowego wyłączenia funkcji, a 504 częściej prowadzi do analizy wydajności i zależności. Gdy już rozpoznasz kod, łatwiej dobrać naprawę, a nie strzelać w ciemno. Następna rzecz, którą zwykle robię po ustaleniu typu błędu, to ustawienie zabezpieczeń, żeby sytuacja nie wracała co kilka dni.
Jak ograniczyć powracające timeouty w dłuższej perspektywie
Jeżeli 504 error wraca regularnie, to nie jest problem do „przeczekania”. To sygnał, że jedna z warstw architektury jest za wolna albo za krucha. W takiej sytuacji największą różnicę robi monitorowanie p95 i p99, czyli czasów, których nie przekracza odpowiednio 95 i 99 procent żądań. Średnia bywa myląca, bo ukrywa pojedyncze, bardzo wolne skoki.
- Ustaw alerty wcześniej, niż backend zacznie dobijać do limitu timeoutu.
- Śledź p95 i p99 dla najważniejszych endpointów, nie tylko średni czas odpowiedzi.
- Rozdziel długie zadania od zwykłych requestów, żeby użytkownik nie czekał na wynik w jednej sesji HTTP.
- Cache'uj dane, które często się powtarzają, zwłaszcza listy, filtry i elementy konfiguracyjne.
- Testuj wpływ zewnętrznych usług, bo integracja z jednym wolnym API potrafi spowolnić cały serwis.
- Przeglądaj logi błędów i metryki po wdrożeniach, a nie dopiero po awarii.
Najlepiej działa podejście warstwowe: najpierw bramka i proxy, potem aplikacja, potem baza danych i zewnętrzne integracje. W praktyce daje to dużo bardziej stabilny system niż samo „podniesiemy timeout, to przestanie sypać błędem”. I właśnie tutaj najłatwiej popełnić kosztowny błąd, który na chwilę ucisza problem, ale nie poprawia jakości całej usługi.
Najdroższy błąd przy timeoutach to leczenie objawu, nie przyczyny
Najczęściej widzę dwa niebezpieczne odruchy: zbyt szybkie uznanie, że winny jest użytkownik, albo bezrefleksyjne wydłużanie timeoutów po stronie infrastruktury. Oba podejścia kuszą, bo dają szybkie wrażenie kontroli, ale nie usuwają źródła opóźnienia. Jeśli aplikacja potrzebuje zbyt dużo czasu na odpowiedź, trzeba znaleźć najwolniejsze ogniwo i je realnie przyspieszyć.
W codziennej pracy stawiam na prostą zasadę: najpierw dokładna diagnostyka, potem mała zmiana, potem ponowny pomiar. Tylko tak da się odróżnić chwilowy incydent od systemowego problemu z wydajnością. Jeśli ten komunikat wraca częściej niż raz na jakiś czas, traktuję go jak sygnał alarmowy, nie jak kosmetyczny błąd przeglądarki.
Jeżeli chcesz szybko sprawdzić, co zrobić dalej, zacznij od logów, czasów odpowiedzi i zależności zewnętrznych. A jeśli błąd 504 pojawia się tylko po Twojej stronie użytkownika, przetestuj inną sieć, wyłącz VPN i zgłoś problem z dokładną godziną oraz adresem podstrony.
