503 Service Unavailable
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
# 2 instanțe × 1.000 cereri/s capacitate
# vârf: 4.000 cereri/s -> 200% încărcare# 6 instanțe × 1.000 cereri/s = 6.000 cereri/s
# vârf: 4.000 cereri/s -> ~67% încărcareCererile 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
healthcheck:
path: /health # verifică și baza de date
timeout: 1s # baza răspunde în 2s la vârfhealthcheck:
path: /health/live # doar procesul
timeout: 3sUn 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
server:
tomcat:
threads:
max: 20server:
tomcat:
threads:
max: 200Câ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ă 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ă.
Reparația
1. Atinge Server aplicație. 2. Setează Instanțe = 6 (4.100 / 6.000 ≈ 68%).
Rezultat: toate cererile sunt tratate, iar serverul are rezervă pentru vârfuri.
De ce merge
La 4.100 de cereri pe secundă (citiri + scrieri), 2 instanțe ajung la peste 200% și surplusul se pierde. Cu 6 instanțe, încărcarea scade la aproximativ 68%, cererile sunt tratate toate și rămâne loc pentru o instanță căzută.
Alte forme ale mesajului
HTTP Error 503. The service is unavailable.503 Service Temporarily Unavailableupstream 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-Afterla 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
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. 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. Server supraîncărcat: CPU 100% chiar pe cea mai mare mașină Ai mărit serverul de câteva ori (mai multe nuclee, mai multă memorie), dar traficul tot îl duce la 100% CPU, iar cererile încep să dureze secunde. Scalarea verticală are o limită și un preț care crește repede; treci la scalare orizontală: mai multe instanțe identice în spatele unui load balancer. Autoscalarea nu ține pasul cu vârful de trafic (instanțele ajung la maxim, cererile tot se pierd) Grupul de autoscalare a ajuns la numărul maxim de instanțe sau pornește instanțe noi prea încet, iar la vârf serverele rămân supraîncărcate. Ridică limita maximă la cât cere vârful real, scalează după o metrică care reacționează devreme și ține un minim care acoperă creșterea bruscă. Î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.
