504 Gateway Timeout
Gateway-ul (nginx, load balancer) a așteptat prea mult după serverul aplicației și a renunțat. Endpointul e prea lent pentru limita gateway-ului: raportează lentoarea, iar pentru operațiile lungi verifică dacă API-ul are o variantă asincronă (202 + job).
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
504 vine de la gateway-ul dintre tine și aplicație: a trimis cererea mai departe, dar aplicația nu a răspuns în timpul lui maxim (des 30 sau 60 de secunde). Aplicația poate termina operația după aceea, deci un POST care a dat 504 poate să fi creat totuși resursa.
Diferențe importante:
- 504 e un răspuns HTTP de la gateway;
- ESOCKETTIMEDOUT e timeout-ul propriului client (Postman), fără răspuns;
- 502 e un răspuns invalid sau o conexiune refuzată, nu o așteptare prea lungă.
Ce faci: măsori cât durează endpointul (Console, timpii), verifici dacă problema apare doar cu anumiți parametri (perioade lungi, fără paginare) și raportezi cu acele detalii. După un 504 la un POST, verifici cu un GET dacă resursa s-a creat, înainte să trimiți din nou.
De ce apare: cauzele frecvente
1Operație lungă sincronă
GET {{baseUrl}}/reports/sales?period=2020-2026 → 504GET {{baseUrl}}/reports/sales?period=2026-10Un interval mai mic reduce timpul de procesare.
2POST retrimis după 504
POST /orders → 504
POST /orders (din nou)GET /orders # verifică dacă s-a creat
# sau trimite cu Idempotency-KeyPrima cerere poate să fi reușit pe server.
Repară eroarea, direct în pagină
Cererea „Raport” (un endpoint care durează aproximativ 2 secunde) nu are nicio limită de timp proprie, deci un client ar aștepta cât decide gateway-ul. Setează în Settings-ul cererii un timeout explicit de 5000 ms, salvează și trimite: trebuie să primești 200.
Indiciu
Request timeout din tabul Settings al cererii.
Reparația
Settings → Request timeout: 5000 ms. Salvează și trimite.
De ce merge
Cu o limită explicită, știi exact cât aștepți și eviți cererile blocate până la timeout-ul gateway-ului. Dacă endpointul depășește limita, primești o eroare clară imediat, iar timpul apare în raportul de performanță. 504 înseamnă că gateway-ul a așteptat prea mult după serviciul din spate. Pentru operații lente, API-urile bune oferă variante asincrone (202 și polling), care evită depășirea timpului.
Alte forme ale mesajului
504 Gateway Time-out nginxHTTP 504The gateway did not receive a timely response from the upstream server
Cum o eviți pe viitor
- Setează un timeout explicit în Settings-ul cererilor lente, ca să știi exact cât aștepți.
- Folosește Idempotency-Key la operațiile de creare, ca retrimiterea să fie sigură.
- Raportează endpointurile care se apropie de limita gateway-ului.
- Măsoară timpul operațiilor lente și discută cu echipa varianta asincronă.
- Nu crește la nesfârșit timeout-ul clientului.
Întrebări frecvente
Cererea a fost procesată?
Poate. Gateway-ul a renunțat, dar aplicația poate fi terminat operația. Verifică înainte de a retrimite.
De ce nu văd 504 în Postman, ci timeout?
Dacă timeout-ul tău e mai mic decât al gateway-ului, Postman renunță primul și vezi ESOCKETTIMEDOUT.
Erori înrudite
Error: ESOCKETTIMEDOUT Serverul nu a trimis niciun răspuns în timpul maxim setat pentru cerere. Mărește timeout-ul (Settings al cererii, Settings global sau --timeout-request în Newman) dacă operația e lentă în mod normal, altfel raportează lentoarea ca problemă de performanță. 502 Bad Gateway Un proxy sau un gateway (nginx, load balancer, API gateway) a primit un răspuns invalid sau niciun răspuns de la serverul aplicației. De obicei aplicația din spate e oprită, repornește sau a căzut. Verifică /health și anunță echipa; nu e o problemă a cererii tale. AssertionError: expected 3499 to be below 1000 Testul verifică o limită (preț sub 1000), dar răspunsul conține valori peste ea. Înainte să raportezi un bug de filtrare, verifică dacă filtrul a fost trimis corect: un parametru scris greșit (max_price în loc de maxPrice) e ignorat de server. Învață Postman de la zero, cu exerciții la fiecare lecție
Curs API Testing cu Postman: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 10 lecții sunt gratuite.
