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

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
• •Set cache headers carefully because temporary 503 responses should not usually be 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

Examples