...
Eroare System Design · Erori HTTP la proxy și load balancer: 502, 503, 504

504 Gateway Timeout

Pe scurt

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

Greșit
Produs p = repo.findById(id);   // fiecare vizualizare merge în bază
// 6.000 citiri/s pe o bază care duce 3.000
Corect
Produs 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ă

Greșit
location /rapoarte {
    proxy_pass http://app;
    proxy_read_timeout 5s;   # raportul durează 20s
}
Corect
# raportul se generează asincron:
# POST /rapoarte -> 202 Accepted + id
# GET  /rapoarte/{id} -> stare / fișier

Operaț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

Greșit
HttpClient client = HttpClient.newHttpClient();
client.send(req, BodyHandlers.ofString());
Corect
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ă tu

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ă.

Alte forme ale mesajului

  • 504 Gateway Time-out
  • HTTP 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

← Toate erorile System Design

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Î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.