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.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Între Postman și aplicație stă adesea un gateway: nginx, un load balancer, un API gateway din cloud. 502 e răspunsul gateway-ului când serverul din spatele lui nu a răspuns corect: conexiune refuzată, răspuns stricat, proces căzut.
Indicii utile:
- body-ul e adesea o pagină HTML a gateway-ului (
<center>nginx</center>), nu JSON-ul API-ului; - toate endpointurile dau 502 în același timp, nu doar unul;
- apare în timpul unui deploy și dispare după un minut.
Ca tester, verifici /health și alte endpointuri: dacă toate dau 502, aplicația e jos și anunți echipa. Dacă doar unul dă 502, probabil acea cerere oprește procesul (un bug grav de raportat). În testele automate, o verificare globală „fără 5xx” transformă situația într-un eșec clar, nu în zeci de erori de parsare JSON.
De ce apare: cauzele frecvente
1Aplicația din spatele gateway-ului e oprită
GET {{baseUrl}}/products → 502 (nginx)# verifică /health, anunță echipa, reîncearcă după deployGateway-ul nu are cui să trimită cererea.
2O cerere anume oprește procesul
POST /import (fișier mare) → 502# raportează: cererea care provoacă oprirea aplicațieiDacă doar acea cerere dă 502, aplicația cade la procesarea ei.
Repară eroarea, direct în pagină
Unele cereri primesc 502 de la gateway, iar testele lor dau erori de parsare greu de citit. Adaugă în scriptul Post-response al colecției „Magazin” un test „Fără eroare de server” care verifică pm.response.code sub 500, apoi trimite „Health”: testul trebuie să treacă.
Indiciu
Scriptul colecției rulează pentru fiecare cerere din ea.
Reparația
Colecția Magazin → Scripts → Post-response:
pm.test("Fără eroare de server", function () {
pm.expect(pm.response.code, "status " + pm.response.code).to.be.below(500);
});De ce merge
Testul rulează după fiecare cerere din colecție. La un 502, raportul arată un singur test clar picat („Fără eroare de server: status 502”), în loc de erori de parsare JSON care ascund cauza. 502 vine de la un gateway sau proxy care nu a primit un răspuns valid de la serviciul din spate. Cererea ta poate fi corectă; problema e în infrastructură, deci o semnalezi echipei.
Alte forme ale mesajului
502 Bad Gateway nginxHTTP 502<html><head><title>502 Bad Gateway</title></head>
Cum o eviți pe viitor
- Pune o verificare globală pentru 5xx în scriptul colecției.
- Nu rula suita în timpul deploy-urilor.
- Un monitor pe
/healthanunță căderile înainte de teste. - Verifică dacă serviciul din spatele gateway-ului rulează înainte să cauți probleme în cerere.
Întrebări frecvente
Ce diferență e între 502 și 504?
502: gateway-ul a primit un răspuns invalid sau o conexiune refuzată. 504: gateway-ul a așteptat prea mult și n-a primit nimic.
De ce body-ul e HTML?
Răspunsul e generat de gateway, care are propriile pagini de eroare, nu de API.
Erori înrudite
503 Service Unavailable Serviciul e temporar indisponibil: în mentenanță, supraîncărcat sau încă pornește după un deploy. Răspunsul poate avea antetul Retry-After. Reîncearcă mai târziu și verifică /health; dacă persistă, anunță echipa. 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). Răspunsul e HTML în loc de JSON (Content-Type: text/html) Endpointul unui API JSON a întors o pagină HTML (des la erori 404 sau 500), deci clienții nu pot citi eroarea. Dacă URL-ul e corect, e un bug de contract: scrie un test pe Content-Type și raportează-l cu cererea atașată. Î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.
