504 Gateway Timeout
Proxy-ul sau load balancer-ul a așteptat răspunsul serverului mai mult decât îi permite timeout-ul și a renunțat. Serverul nu e neapărat căzut, ci lent: de obicei din cauza bazei de date supraîncărcate, a unei interogări fără index sau a unui serviciu extern apelat sincron.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
504 Gateway Timeout vine de la intermediar (nginx, ALB, API gateway, CDN): a trimis cererea la server, a așteptat cât îi permite configurația (de exemplu 60 de secunde la nginx, proxy_read_timeout) și nu a primit niciun răspuns. Serverul poate încă lucra la cerere, dar clientul a primit deja eroarea.
Cauza este aproape întotdeauna în aval: o bază de date care nu mai face față și răspunde în secunde în loc de milisecunde, o interogare care scanează tot tabelul, un apel la un serviciu extern fără timeout, un lock ținut prea mult. Mărirea timeout-ului din proxy doar ascunde problema și ține mai multe conexiuni ocupate.
Pornește de la cererile lente: în logurile aplicației, caută durata fiecărei cereri și ce a făcut în timpul acela (timpul petrecut în bază, în apeluri HTTP externe). În tracing (OpenTelemetry, Jaeger) vezi direct segmentul care durează.
De ce apare: cauzele frecvente
1Baza de date e supraîncărcată de citiri repetate
Produs p = repo.findById(id); // fiecare vizualizare merge în bază
// 6.000 citiri/s pe o bază care duce 3.000Produs p = cache.get(id);
if (p == null) {
p = repo.findById(id);
cache.set(id, p, Duration.ofMinutes(5));
}Peste capacitate, latența bazei crește brusc și cererile depășesc timeout-ul proxy-ului. Un cache pentru datele citite des scoate majoritatea citirilor din bază.
2Timeout-ul proxy-ului e mai mic decât operația normală
location /rapoarte {
proxy_pass http://app;
proxy_read_timeout 5s; # raportul durează 20s
}# raportul se generează asincron:
# POST /rapoarte -> 202 Accepted + id
# GET /rapoarte/{id} -> stare / fișierOperațiile lungi nu se țin într-o cerere HTTP. Pornești jobul, răspunzi imediat și clientul verifică starea mai târziu.
3Apel extern fără timeout
HttpClient client = HttpClient.newHttpClient();
client.send(req, BodyHandlers.ofString());HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(2)).build();
HttpRequest req = HttpRequest.newBuilder(uri)
.timeout(Duration.ofSeconds(3)).build();Fără timeout, un furnizor lent blochează cererea până când proxy-ul renunță. Cu timeout propriu, aplicația răspunde controlat (eroare clară, fallback).
Repară eroarea, direct în pagină
Paginile de produs dau 504 Gateway Timeout la vârf: 6.000 de citiri pe secundă ajung direct în baza SQL, care duce doar 3.000. Fă ca toate cererile să fie tratate, cu baza sub 70% încărcare, fără să schimbi baza de date.
Indiciu
Citirile repetate ale acelorași produse nu trebuie să ajungă de fiecare dată în bază.
Reparația
1. Adaugă componentă → Cache (Redis). 2. Conectează Server aplicație → Cache (Redis). 3. Lasă rata de hit la 80% (sau mai mult).
Rezultat: în bază ajung 6.000 × 20% = 1.200 de citiri pe secundă plus scrierile, adică aproximativ 50% încărcare.
De ce merge
Baza era la peste 200%: latența ei crește de zeci de ori și cererile depășesc timeout-ul proxy-ului. Un cache cu rată de hit de 80% lasă să ajungă în bază doar 1.200 de citiri pe secundă, iar baza revine la o încărcare sănătoasă.
Alte forme ale mesajului
504 Gateway Time-outHTTP 504 Gateway Timeout (ALB)Error 504: Gateway timeout (Cloudflare 524: A timeout occurred)
Cum o eviți pe viitor
- Pune timeout-uri pe fiecare apel (bază, HTTP, cache), mai mici decât cel al proxy-ului.
- Ține baza de date sub 70–80% încărcare: cache pentru citiri, replici, indexuri.
- Mută operațiile lungi în joburi asincrone (coadă + workeri).
- Monitorizează latența p95/p99, nu doar media: 504 apar în coada distribuției.
Întrebări frecvente
Să măresc proxy_read_timeout?
Doar dacă operația e legitim mai lungă și rară. Pentru trafic obișnuit, timeout-ul mai mare ține conexiunile ocupate mai mult și agravează supraîncărcarea. Repară cauza lentoarei.
Cererea a dat 504, dar comanda s-a salvat. Cum e posibil?
Proxy-ul a renunțat, dar serverul a continuat și a terminat. De aceea operațiile de scriere trebuie să fie idempotente: clientul care reîncearcă nu trebuie să creeze a doua comandă.
Erori înrudite
502 Bad Gateway Proxy-ul sau load balancer-ul din fața aplicației a primit un răspuns invalid de la server, de obicei pentru că procesul aplicației a căzut, a repornit sau nu ascultă pe portul configurat. Verifici întâi logurile aplicației și ale proxy-ului, apoi health check-ul care trebuie să scoată instanțele moarte din rotație. upstream timed out (110: Connection timed out) while reading response header from upstream Linia din logul de erori nginx care stă în spatele unui 504: nginx a trimis cererea la server și nu a primit nici măcar antetele răspunsului în `proxy_read_timeout`. Caută ce face serverul atât de mult: o operație lungă ținută sincron (un apel extern, un raport) se mută într-un job asincron. 499 Client Closed Request Codul 499 apare doar în logurile nginx: clientul (browserul, aplicația mobilă sau un alt serviciu) a închis conexiunea înainte ca serverul să răspundă, pentru că s-a săturat să aștepte. Problema reală e lentoarea: află de ce durează cererile atât de mult. Baza de date primară la 100% CPU din cauza citirilor Majoritatea interogărilor sunt citiri, iar baza primară, singura care le servește, a ajuns la limită. Mută citirile pe replici de citire (read replicas) și pune un cache în față pentru datele citite des; primara rămâne pentru scrieri. Învață System Design de la zero, cu exerciții la fiecare lecție
Curs System Design: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 10 lecții sunt gratuite.
