Czym jest błąd 504 i czym różni się od 502, 503 i 500

HTTP 504 Gateway Timeout to kod z rodziny 5xx opisany w specyfikacji HTTP Semantics (RFC 9110). Definicja jest wąska: serwer pełniący rolę pośrednika przekazał żądanie dalej i nie doczekał się odpowiedzi w zadanym oknie czasowym. Ten kod nie mówi, czy padło PHP, czy MySQL mielił zapytanie 40 sekund — mówi wyłącznie „nie dostałem odpowiedzi na czas”.

W typowym stacku sklepu na PrestaShop lub WooCommerce gatewayem jest ten element, który stoi przed aplikacją: Nginx → PHP-FPM → MySQL, a przy włączonym CDN łańcuch wydłuża się do Cloudflare → Nginx → PHP-FPM → MySQL. Do tego dochodzą zewnętrzne API: bramka płatności, kurier, ERP, system faktur. Każde ogniwo ma własny timeout i każde może zwrócić 504 — dlatego pierwszy krok to ustalenie, kogo tak naprawdę nie doczekał się proxy.

Kod	Kiedy zobaczysz ten kod	Gdzie szukać
504	Proxy nie doczekał się odpowiedzi od upstreamu (PHP-FPM, Apache, API)	nginx error.log, slow log PHP-FPM, slow query log MySQL
502	Upstream odpowiedział, ale niepoprawnie — proces PHP-FPM padł lub nie przyjął połączenia	log PHP-FPM, logi modułów PHP (np. fatal error), OOM killer
503	Serwer działa, ale świadomie odmawia obsługi (restart, tryb konserwacji, limit workerów)	konfiguracja Nginx, panel hostingu, harmonogram maintenance
500	Aplikacja wykonała się i zwróciła błąd — składnia, wyjątek, brak uprawnień	log błędów PHP, debug w PrestaShop, log WooCommerce

Pułapka: Cloudflare po przekroczeniu własnego limitu (100 sekund na niższych planach) zwraca kod 524, a nie 504. Dla użytkownika wygląda to identycznie — biała strona i „timeout”. Rozróżnienie jest proste: jeśli w nagłówkach odpowiedzi widzisz server: cloudflare, a w error.log Nginxa nie ma żadnego wpisu o tym żądaniu, problem leży między CDN a originem — origin nawet nie dostał ruchu. Zanim zaczniesz zmieniać konfigurację serwera, sprawdź to jedno.

Szybka diagnoza: hosting, sklep czy zewnętrzna integracja?

Cztery testy, każdy po 2–3 minuty. Wykonaj je po kolei i zapisz wyniki — to skróci rozmowę z hostingiem z trzech dni do jednej wiadomości.

1. Zakres błędu. Sprawdź osobnymi wejściami: stronę główną, /admin (panel PrestaShop lub /wp-admin), /koszyk i /kasa oraz jedną akcję zapisu (np. dodanie produktu w panelu). Jeśli 504 leci tylko przy kasie — szukaj w koszyku i sesjach. Jeśli tylko w /admin przy zapisie produktu — szukaj w module, który ten zapis obsługuje.
2. Izolacja proxy i cache. Otwórz ten sam URL w oknie incognito, na innym łączu (LTE z telefonu) i po wyłączeniu CDN (np. na czas testu wyłącz pomarańczową chmurkę w Cloudflare). Jeśli po LTE jest szybko, a w firmie wolno — to problem sieci lub cache przeglądarki. Jeśli po wyłączeniu CDN błąd znika, wina leży po stronie proxy/CDN, nie aplikacji.
3. Korelacja czasowa. Zapytaj siebie i zespół: co działo się w ostatnich 72 godzinach? Wdrożenie na produkcję, nowy moduł, aktualizacja WooCommerce lub PrestaShop, włączenie nowej integracji (płatności, kurier, ERP, newsletter). 504 niemal nigdy nie pojawia się „z niczego” — pojawia się razem ze zmianą.
4. Pomiar czasu. Uruchom z terminala: curl -s -o /dev/null -w "dns:%{time_namelookup} connect:%{time_connect} ttfb:%{time_starttransfer} total:%{time_total}\n" https://twojadomena.pl/koszyk. Zobaczysz, po ilu sekundach serwer odpuszcza. Jeśli total wynosi dokładnie 60,0 s — to limit konfiguracji, nie wolne zapytanie. Jeśli 12,4 s przy ttfb 12,2 s — wąskim gardłem jest aplikacja.

Wniosek jest dwuwartościowy. 504 globalny, na wszystkich podstronach, także w /admin — problem po stronie serwera lub upstreamu (PHP-FPM, MySQL, throttling hostingu). 504 punktowy, dotyczący jednego URL-a lub jednej akcji — problem w skrypcie, module albo zewnętrznym API, które nie odpowiada w rozsądnym czasie.

Jak w 10 minut ustalić źródło błędu — logi, które naprawdę coś mówią

1. Nginx error.log. Zaczynasz od: grep -i "upstream timed out" /var/log/nginx/error.log | tail -50, a potem grep -i "while reading response header from upstream" /var/log/nginx/error.log. Pierwszy wpis pokazuje, który upstream nie odpowiedział (php-fpm czy zewnętrzne API) i jaki URL był obsługiwany. To najszybsza informacja, jaką w ogóle dostaniesz.

2. Slow log PHP-FPM. W konfiguracji pool (zwykle /etc/php/*/fpm/pool.d/www.conf) ustaw na czas diagnozy request_slowlog_timeout = 5s oraz slowlog = /var/log/php-fpm/slow.log. Plik slow log zawiera stack trace: konkretny plik i konkretną funkcję, która przekroczyła limit. Nie zgadujesz już, czy winny jest moduł płatności, czy eksport zamówień — widzisz to wprost.

3. Slow query log MySQL. Włącz slow_query_log, ustaw long_query_time = 2. Zapytania analizuj przez mysqldumpslow -s t albo pt-query-digest, a najlepiej powtarzające się zapytanie obejrzyj przez EXPLAIN. 504 w koszyku i na stronie zamówienia to bardzo często brak indeksu: w PrestaShop na tabeli koszyka, w WooCommerce na wp_woocommerce_sessions, która rośnie do setek megabajtów.

4. Metryki hostingu. Zestaw godzinę błędu z wykresami CPU, RAM i I/O w panelu. Na hostingu współdzielonym zobaczysz throttling — serwer celowo dusi proces, zanim ten skończy pracę.

Błąd 504 w PrestaShop — 6 najczęstszych przyczyn

W PrestaShop błąd 504 najczęściej dotyczy zadań administracyjnych, a nie zwykłego wejścia na stronę. Jeśli log Nginx pokazuje 504 na /admin.../index.php, sprawdź po kolei te sześć przypadków:

• Przebudowa indeksu wyszukiwarki — Katalog → Szukaj → przebudowa indeksu idzie w jednym żądaniu. Przy 40 000 produktów i dwóch językach to 80 000 rekordów w ps_product_lang plus zapisy do tabel indeksu. Przy fastcgi_read_timeout 60 żądanie padnie w połowie i zostawi częściowy indeks. Indeksowanie przenieś do crona (Zaawansowane → Cron) albo komendy CLI.
• Import i eksport CSV — Zaawansowane → Import to jedno żądanie na cały plik. 20 000 wierszy aktualizacji stanów to dziesiątki tysięcy zapytań do ps_product, ps_product_lang i ps_stock_available. Dziel plik na paczki po 1000–2000 wierszy albo importuj skryptem przez CLI/API. To samo dotyczy eksportu 50 000 zamówień.
• Masowe faktury PDF — setki dokumentów generowanych po stronie PHP, a jeśli robi to moduł ERP, dochodzi request do zewnętrznego API księgowego. Bez kolejki każda faktura wydłuża jedno żądanie.
• API kurierów i płatności — InPost, DPD, DHL, Przelewy24. Gdy moduł nie ustawia CURLOPT_TIMEOUT i CURLOPT_CONNECTTIMEOUT, przy awarii API żądanie wisi bardzo długo i blokuje workera PHP-FPM.
• Brak indeksów po migracji — stare zapytania modułów 1.6 pod 1.7/8.x potrafią robić LIKE '%fraza%' na ps_product_lang i skanować całą tabelę. Potwierdź to przez EXPLAIN i slow query log MySQL.
• Smarty kompilowany na produkcji — Zaawansowane → Wydajność: „Wymuś kompilację” plus czyszczenie cache przy każdym żądaniu oznacza kompilowanie szablonów od zera. Objaw: 504 tuż po deployu, po kilku minutach przechodzi.

Zanim dodasz własny indeks, sprawdź w dokumentacji PrestaShop dla deweloperów, jak zbudowane są tabele i relacje — indeks założony na złą kolumnę zwiększa tylko czas zapisów.

Błąd 504 w WooCommerce — 6 najczęstszych przyczyn

WooCommerce stoi na innym stacku: WordPress, wtyczki, WP-Cron i często HPOS. Dlatego przyczyny 504 wyglądają inaczej niż w PrestaShop.

• WP-Cron odpalany przy każdym wejściu — domyślnie WordPress nie ma systemowego crona. Każde żądanie sprawdza harmonogram i odpala zaległe zadania w tle (loopback do wp-cron.php). Przy małym ruchu import, wysyłka maili czy raport startują dopiero wtedy, gdy ktoś wejdzie na stronę — i blokują ten request. Ustaw define('DISABLE_WP_CRON', true) w wp-config.php i odpalaj zadania z crontab co minutę przez wp cron event run --due-now.
• Wtyczki synchronizacyjne bez kolejki — ERP, hurtownia, marketplace. Przycisk „Synchronizuj teraz” robi pełną synchronizację 20 000 SKU w jednym żądaniu, przy limicie API rzędu 100 zapytań na minutę. Efekt: setki sekund i 504. Docelowo paczki po 100–500 rekordów przez Action Scheduler (WooCommerce → Status → Zaplanowane akcje) albo wp action-scheduler run.
• HPOS i stare meta_query — od WooCommerce 8.x zamówienia siedzą w wc_orders i wc_orders_meta, nie w wp_postmeta. Wtyczki pisane pod stare tabele pytają o meta_value, który nie ma indeksu — przy 100 000 zamówień to pełny skan. Sprawdź Query Monitor i czas najwolniejszego zapytania.
• Webhooki i callbacki płatności — kasa czeka, aż bramka potwierdzi płatność, kod zaktualizuje zamówienie, wyśle mail i powiadomi ERP. Wszystko synchronicznie, w jednym żądaniu. Klasyczny 504 przy płatności; pilnuj duplikatów, gdy klient kliknie drugi raz.
• Za duże shortcode'y i listingi — [products limit="-1"] albo strona kategorii z liczeniem wariantów zmusza WooCommerce do policzenia ceny i stanu dla każdej wariacji. To problem katalogu, nie serwera — podnoszenie timeoutu nic nie da.
• Brak object cache — bez Redisa każde żądanie odtwarza te same zapytania o opcje, terminy i meta. Przy 50 równoczesnych użytkownikach MySQL dobija do max_connections, PHP-FPM czeka, Nginx zwraca 504.

Naprawa krok po kroku — co zmienić, w jakiej kolejności i czego nie ruszać

Kolejność ma znaczenie. Zacznij od ustalenia, co dokładnie kończy się 504 — RFC 9110 definiuje ten kod jako timeout po stronie pośrednika (Nginx, Cloudflare, load balancer), a nie aplikacji. To znaczy, że PHP mógł skończyć pracę, a klient i tak dostał błąd.

1. Znajdź URL i akcję. grep " 504 " /var/log/nginx/access.log pokaże konkretne adresy, godziny i liczbę wystąpień. Sprawdź, czy to koszyk, admin-ajax.php, czy eksport. Jeden URL powtarzający się w kółko to problem w kodzie lub zapytaniu, nie w serwerze.
2. Staging i kopia bazy. mysqldump przed każdą zmianą. Dodanie indeksu na tabeli z 2 mln wierszy potrafi na minuty zablokować zapisy — na produkcji rób to w oknie serwisowym, nie „na oko”.
3. Limity — i różnica między nimi. Patrz tabela. Kluczowe: na Linuksie max_execution_time nie liczy czasu spędzonego na zapytaniach do bazy i wywołaniach curl, więc samo podniesienie go w php.ini często nic nie zmienia. Nginx po swoim fastcgi_read_timeout zwraca 504, zostawiając zajętego workera PHP-FPM.
4. Długie operacje do kolejki. WP-CLI, Action Scheduler, cron systemowy, a w PrestaShop Symfony Messenger (bin/console). 500 faktur generowanych komendą z crona to 500 krótkich żądań zamiast jednego wiszącego.
5. Zapytania. EXPLAIN na najwolniejszym zapytaniu, indeks złożony zamiast pojedynczego, przepisanie meta_query, cache wyników w Redis/Memcached (PrestaShop: Zaawansowane → Wydajność, wymaga rozszerzenia php-redis).
6. Kiedy podnosić limit. Jeśli jednorazowa operacja trwa 90 s — podnieś fastcgi_read_timeout na czas jej wykonania i wróć do poprzedniej wartości. Jeśli 504 dotyczy zwykłego wejścia na stronę albo kasy — nie. Limit 30 s z komunikatem „spróbuj ponownie” jest lepszy niż 300 s, które przy 4 workerach wyłącza sklep z użytku.
7. Pułapki. Po edycji pliku Nginx: nginx -t && systemctl reload nginx — bez reloadu zmiana nie działa. Sprawdź nginx -T, który wypisuje pełną złożoną konfigurację i pokazuje, który plik faktycznie wygrywa. Zmiany robione ręcznie na serwerze wrócą przy najbliższym deployu — trzymaj je w repozytorium lub narzędziu do provisioningu.

Kiedy błąd 504 to wina hostingu — i jak rozmawiać z dostawcą

Błąd 504 na statycznych plikach (np. logo.png, style.css) to prawie zawsze wina infrastruktury. Aplikacja PHP nie jest wtedy w ogóle wywoływana — Nginx czeka na FastCGI, którego nie ma. Podobnie, gdy 504 pojawia się na kilku niepowiązanych aplikacjach na tym samym koncie (sklep, blog, panel). To znak, że problem leży w warstwie współdzielonej: throttling CPU/I/O, przeciążony serwer MySQL albo awaria upstreamu u dostawcy CDN (Cloudflare, Bunny).

Od supportu wymagaj trzech rzeczy: logu z Nginx z dokładnymi timestampami (nie „u nas działa”), wartości fastcgi_read_timeout (domyślnie 60 s, w niektórych panelach 30 s) oraz informacji o limitach CPU/RAM/I-O i ewentualnym throttlingu. Bez tego nie odróżnisz chwilowego skoku ruchu od stałego niedoboru zasobów.

Zgłoszenie musi zawierać: konkretny URL, godzinę z sekundami, kod HTTP, dowód z curl -I (np. curl -I https://twojsklep.pl/koszyk) i output z zakładki Network w DevTools (czas oczekiwania, status). Zamiast „sklep nie działa” wyślij zrzut ekranu z 504 i nagłówkiem X-Request-ID, jeśli hosting go dodaje.

Hosting współdzielony ma limity, których nie przeskoczysz. VPS daje kontrolę nad php-fpm i MySQL, ale wymaga administracji. Hosting zarządzany to kompromis — ktoś inny pilnuje stosu, ale nadal możesz trafić na throttling. Migracja na VPS ma sens, gdy 504 występuje regularnie przy normalnym ruchu (np. 50 zamówień dziennie), a hosting współdzielony nie potrafi wskazać przyczyny. Jeśli 504 pojawia się raz na miesiąc przy imporcie 10 000 produktów, VPS to zbędny wydatek — lepiej zakolejkować import.

Gdy hosting potwierdzi poprawne logi i limity, problem jest w kodzie. Moduł płatności, stary plugin do kuriera, pętla w foreach odpyłująca API bez timeoutu — to typowi sprawcy. Wtedy czas na dewelopera i analizę dokumentacji deweloperskiej PrestaShop lub kodu wtyczki WooCommerce.

Jak zapobiegać błędowi 504 — monitoring i higiena wdrożeń

Monitoring zewnętrzny to podstawa. Uptime robot co 1 min na stronę główną to za mało. Dodaj checki na /koszyk i /logowanie — one odpyłują bazę i sesje. Alert ustaw na 5xx z progiem: np. 3 błędy w ciągu 5 minut. Codzienne maile „raport dzienny” trafiają do kosza — chyba że sklep padnie w nocy.

Importy, synchronizacja ERP, generowanie raportów — to musi działać poza requestem użytkownika. Cron lub worker (np. php bin/console w PrestaShop, WP-CLI w WooCommerce) z limitem czasu i kolejką. Jeśli import 50 000 produktów trwa 20 minut, nie może blokować PHP-FPM dla klientów. Ustaw max_execution_time tylko dla skryptu CLI, nie dla całego serwera.

Każda integracja zewnętrzna — płatności (Przelewy24, PayU), kurier (InPost, DPD), ERP — musi mieć własny timeout (np. 5 s) i retry z backoffem (1 s, 2 s, 4 s). Bez tego awaria API przewraca sklep: PHP czeka 60 s na odpowiedź, Nginx zwraca 504. Sprawdź, czy moduł nie robi zapytań synchronicznie w koszyku.

Cache na trzech poziomach: object cache (Redis) dla zapytań MySQL, page cache (np. LSCache, WP Rocket) dla HTML, CDN dla statyków. Pamiętaj o regułach: nie cache'uj /koszyk, /kasa, /admin, /moje-konto. Te URL-e muszą być zawsze świeże — inaczej klient zobaczy cudzy koszyk.

Staging i testy wydajnościowe przed wdrożeniem to obowiązek przy zmianach modułów płatności i kurierów. Wystarczy prosty test: 10 równoczesnych użytkowników dodających produkt do koszyka. Backup bazy i plików z testem odtworzenia — raz w miesiącu odtwórz kopię na stagingu. Backup, którego nie sprawdziliśmy, nie jest backupem.

W DropDigital administracja serwerem obejmuje monitoring, aktualizacje bezpieczeństwa, konfigurację cache i kolejek oraz reakcję na incydenty. SLA do 4 h na reakcję ma sens, gdy sklep zarabia na zamówieniach — każda godzina przestoju to realna strata. Koszt takiego wsparcia to zwykle 500–1500 zł netto miesięcznie, w zależności od liczby integracji i ruchu.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Ustal zakres błędu — Sprawdź kolejno: cała strona, tylko /admin, konkretna podstrona (koszyk, kasa), jedna akcja (zapis produktu, import). Globalny 504 wskazuje na serwer lub upstream, punktowy — na skrypt albo zewnętrzne API.
• Powtórz test w trybie incognito — Wyklucza cache przeglądarki i stary, zawieszony request. Jeśli w incognito działa, a normalnie nie — sprawdź sesję i cache serwera.
• Powtórz test na innym łączu (LTE) — Izoluje problem od Twojej sieci firmowej i lokalnego DNS. Błąd obecny na obu łączach jest po stronie serwera lub aplikacji.
• Sprawdź nagłówki odpowiedzi — W narzędziach deweloperskich zobacz pole server i rzeczywisty kod. Rozstrzygnij, czy masz 504 od własnego proxy, czy 524 od Cloudflare — to dwie różne ścieżki naprawy.
• Zmierz czas odpowiedzi przez curl — curl -o /dev/null -s -w "time_total: %{time_total}\ntime_starttransfer: %{time_starttransfer}\n" https://twojadomena.pl/URL. Pozwala ustalić, po ilu sekundach serwer odpuszcza i czy problem jest w nagłówkach, czy w treści.
• Przejrzyj nginx error.log — Szukaj wpisów „upstream timed out (110: Connection timed out)” i „while reading response header from upstream”. Log pokazuje, który upstream i który URL przekroczył limit.
• Włącz PHP-FPM slow log — Ustaw request_slowlog_timeout na wartość nieco niższą niż limit, np. 15 s. Plik slowlog wskaże dokładny skrypt i funkcję, która się zawiesza — zamiast zgadywania.
• Sprawdź MySQL slow query log — Szczególnie gdy 504 pojawia się w koszyku lub przy składaniu zamówienia. Powtarzające się zapytanie przeanalizuj przez EXPLAIN — brak indeksu na tabeli koszyka to klasyczna przyczyna.
• Zweryfikuj metryki hostingu — W panelu sprawdź CPU, RAM i I/O w minutach, w których wystąpił błąd. Na hostingu współdzielonym throttling potrafi wyglądać dokładnie jak 504.
• Sprawdź zmienne limitów w php.ini — max_execution_time, max_input_time, memory_limit, request_terminate_timeout, fastcgi_read_timeout, proxy_read_timeout. Zapisz wartości przed zmianą, żeby móc wrócić do punktu wyjścia.
• Przejrzyj zmiany z ostatnich 72 godzin — Wdrożenia, nowe moduły, aktualizacja PrestaShop lub WooCommerce, nowa integracja (płatności, kurier, ERP). Jeśli 504 pojawił się po zmianie — zacznij od jej cofnięcia na stagingu.
• Sprawdź, czy 504 nie wisi na zewnętrznym API — Bramka płatności, API kuriera, synchronizacja z ERP. Jeśli żądanie idzie na zewnątrz, Twój serwer czeka bezczynnie — to nie jest problem wydajności Twojej maszyny.
• Sprawdź konkretną akcję zapisu — Zapis produktu, edycja zamówienia, masowa zmiana cen. Jeśli 504 pojawia się tylko przy zapisie, podejrzewaj hook modułu lub zapytanie UPDATE bez indeksu.
• Zabezpiecz konfigurację przed zmianami — Skopiuj aktualne pliki konfiguracyjne Nginx, PHP-FPM i wartości php.ini. Każdą zmianę wprowadzaj pojedynczo, żeby wiedzieć, co pomogło — albo co pogorszyło sytuację.

Najczęściej zadawane pytania

Źródła i materiały

• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – dane strukturalne
• Google Search Central – Core Web Vitals
• PrestaShop – dokumentacja dla deweloperów
• RFC 9110 – HTTP Semantics