503 Service Unavailable
This is an educational reference page about HTTP 503 Service Unavailable. The page itself is served as 200 OK so it can be indexed as HTTP documentation.
The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.
What it means
HTTP 503 means the server is temporarily unable to handle the request.
Common causes
- Maintenance mode, overloaded workers, deploy restarts, or exhausted capacity.
- A dependency is down and the service is intentionally unavailable.
- Traffic spikes exceed configured concurrency or queue limits.
How to fix it
- Send Retry-After when clients should retry later.
- Surface maintenance pages for humans and clear JSON for API clients.
- Scale capacity, shed load, or reduce expensive work during overload.
Example response
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: application/json
{"error":"Service temporarily unavailable"}Developer notes
503 is usually temporary. If a proxy cannot reach a bad upstream response, 502 or 504 may be more accurate.