Service Unavailable

Server perspective

Use 503 when the service is temporarily unable to handle requests because of overload, maintenance, or another short-lived capacity issue.

When to use

• •Return 503 for planned maintenance windows, brownouts, dependency saturation, or temporary capacity protection
• •Use it when recovery is expected, even if the exact time is uncertain
• •Scheduled maintenance downtime
• •Server overload or high traffic
• •Database maintenance
• •Temporary service outages
• •CPU, connection pool, or memory capacity exhaustion protecting the service from cascading failure

How to respond

• •Send Retry-After when you can estimate when the service should be available again
• •Serve a clear maintenance or overload response and make sure health checks, load balancers, and autoscaling signals understand the degraded state

Headers to consider

• •Retry-After is recommended when you know an estimated recovery time
• •503 responses should not be cached without explicit cache controls; set Cache-Control: no-store unless you intentionally want an outage page cached.

Response body

• •Include a user-friendly explanation and, for APIs, a stable error code plus any retry guidance or status-page link

Server-side pitfalls

• •Do not use 503 for caller-specific throttling when 429 Too Many Requests is the clearer signal
• •Do not hide known upstream protocol failures behind 503 when 502 or 504 is more accurate
• •Permanent service shutdown (use 410 Gone)
• •Bad upstream responses (use 502 Bad Gateway)
• •Client rate limiting (use 429 Too Many Requests)

Examples