HTTP 503 Service Unavailable
ID: networking/http-503-service-unavailable
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| any | active | — | — | — |
Root Cause
The server is temporarily unable to handle the request due to being overloaded, under maintenance, or having no healthy backend instances. This is typically a transient condition indicated by the Retry-After header when present.
genericWorkarounds
-
88% success Scale up the backend service and ensure healthy instances are available
1. Check if any backend instances are running: kubectl get pods or systemctl status app 2. Check health check status in your load balancer console 3. Scale up instances: kubectl scale deployment app --replicas=3 4. Check resource usage on existing instances: top, free -m, df -h 5. If OOM killed, increase memory limits and restart 6. Verify health check endpoint responds: curl http://backend:port/health 7. Check if a maintenance page is active and disable it
-
85% success Implement proper retry logic with exponential backoff and circuit breakers
1. Respect the Retry-After header if present in the 503 response 2. Implement exponential backoff: initial 1s, multiply by 2, max 60s 3. Add jitter to prevent thundering herd: delay = base_delay * 2^attempt + random(0, 1000ms) 4. Implement a circuit breaker pattern to stop retries after N consecutive failures 5. Queue requests during outages and process them when the service recovers 6. Set up monitoring and alerting for 503 error rates
Dead Ends
Common approaches that don't work:
-
Aggressively retry with no delay or backoff
85% fail
If the server is overloaded, rapid retries add more load and make the situation worse. This can trigger rate limiting, IP bans, or cascade failures across the infrastructure. The Retry-After header, when present, should be respected.
-
Assume the application code is broken and redeploy without checking infrastructure
75% fail
503 errors are typically infrastructure-level (overload, maintenance, no healthy backends), not application-level bugs. Redeploying the same code does not add server capacity, fix a drained connection pool, or end a maintenance window.