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

503 Service Unavailable

Pe scurt

Serverul (sau load balancer-ul din fața lui) spune că nu poate trata cererea acum: e supraîncărcat, în mentenanță sau nu are nicio instanță sănătoasă. De obicei repari adăugând capacitate (mai multe instanțe, autoscalare) și verificând de ce instanțele sunt marcate nesănătoase.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

503 Service Unavailable înseamnă „încearcă mai târziu”: serviciul există, dar în acest moment nu poate răspunde. Spre deosebire de 500 (o eroare în cod), 503 descrie o stare temporară a sistemului.

În practică îl vezi în trei situații: serverele sunt peste capacitate și refuză cereri noi (coada de conexiuni e plină, pool-ul de thread-uri e ocupat); load balancer-ul nu mai are nicio țintă sănătoasă (toate instanțele pică health check-ul); sau aplicația e pusă intenționat în mentenanță. Unele componente trimit și antetul Retry-After, cu numărul de secunde după care merită reîncercat.

Ca să afli care e cazul, compară momentul erorilor cu graficul de trafic și cu numărul de instanțe sănătoase din load balancer. Dacă 503 apare exact la vârfuri, problema e capacitatea; dacă apare și la trafic mic, problema e starea instanțelor.

De ce apare: cauzele frecvente

1Prea puține instanțe pentru vârful de trafic

Greșit
# 2 instanțe × 1.000 cereri/s capacitate
# vârf: 4.000 cereri/s  ->  200% încărcare
Corect
# 6 instanțe × 1.000 cereri/s = 6.000 cereri/s
# vârf: 4.000 cereri/s  ->  ~67% încărcare

Cererile peste capacitate nu au unde să fie tratate și sunt refuzate. Dimensionezi pentru vârf, cu rezervă, nu pentru medie.

2Toate țintele pică health check-ul

Greșit
healthcheck:
  path: /health        # verifică și baza de date
  timeout: 1s          # baza răspunde în 2s la vârf
Corect
healthcheck:
  path: /health/live   # doar procesul
  timeout: 3s

Un health check prea strict marchează nesănătoase toate instanțele deodată când o dependență e lentă, iar load balancer-ul răspunde 503 la tot traficul.

3Pool-ul de thread-uri al serverului e plin

Greșit
server:
  tomcat:
    threads:
      max: 20
Corect
server:
  tomcat:
    threads:
      max: 200

Când toate thread-urile sunt ocupate cu cereri lente, cererile noi stau la coadă, apoi sunt refuzate. Cauza reală e adesea o dependență lentă; mărirea pool-ului doar câștigă timp.

Repară tu

Repară eroarea, direct în pagină

În campania de reduceri, magazinul primește 4.000 de citiri pe secundă, iar cele 2 instanțe ale serverului (1.000 de cereri/s fiecare) răspund cu 503 Service Unavailable la o parte din cereri. Dă serverului destulă capacitate ca toate cererile să fie tratate, cu toate componentele sub 80%.

Indiciu

Împarte traficul de vârf la capacitatea unei instanțe și adaugă rezervă.

Alte forme ale mesajului

  • HTTP Error 503. The service is unavailable.
  • 503 Service Temporarily Unavailable
  • upstream connect error or disconnect/reset before headers (Envoy, cu 503)

Cum o eviți pe viitor

  • Dimensionează pentru vârf, cu instanțele sub 70–80% încărcare.
  • Activează autoscalarea, cu un minim care ține vârful obișnuit.
  • Separă health check-ul de liveness (procesul trăiește) de cel de readiness (poate primi trafic).
  • Trimite Retry-After la mentenanță și la supraîncărcare, ca clienții să nu reîncerce imediat.

Întrebări frecvente

Ce cod trebuie să întoarcă aplicația când e supraîncărcată?

503, de preferat cu Retry-After. Așa clienții și load balancer-ele înțeleg că e o problemă temporară. Un 500 sugerează un bug și nu spune nimic despre când merită reîncercat.

E 503 același lucru cu 429?

Nu. 429 înseamnă că acel client a depășit limita lui (rate limiting). 503 înseamnă că serviciul nu poate răspunde nimănui în acel moment.

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.