503 Service Unavailable: HTTP Status Code Meaning, Causes, and Fixes

What 503 Service Unavailable means

503 Service Unavailable means the server is healthy enough to respond but cannot process this request right now. Two main scenarios: scheduled maintenance (deployment in progress, restart window) and overload (more requests than the server can handle). The response should include a Retry-After header so clients know when to come back. 503 is preferable to crashing or letting the request queue grow unbounded; it tells clients explicitly to back off.

When servers should return it: Return 503 when the server is intentionally rejecting requests due to overload, maintenance, or a circuit breaker tripping. Always include Retry-After.

Common causes

Deployment in progress
Server overloaded, intentional shedding
Circuit breaker tripped due to dependency failures
Database under maintenance
Autoscaling lag (traffic spike, instances still booting)

How to fix 503 Service Unavailable

Wait the time given in Retry-After
Retry with exponential backoff
For consistent 503s, the service has a capacity or availability problem
For your own service, add capacity, fix the failing dependency, or fall back to cached data

Example response

HTTP/2 503
retry-after: 30
content-type: text/plain
Service temporarily unavailable due to maintenance

Related status codes

Frequently Asked Questions

503 vs 429?

503 = service-wide unavailable. 429 = you specifically are over your rate limit (others are fine).

503 vs 504?

503 = the server itself is unavailable / overloaded. 504 = an upstream the server depends on did not respond in time.

Should I show a maintenance page or return 503?

Both. Return 503 with a Retry-After header AND serve a friendly maintenance HTML body. Search engines understand 503 means "temporary", so they will not deindex your pages.

More references

For a one-page reference of all HTTP status codes, see the HTTP cheat sheet. For testing API responses, try the API Tester tool. For inspecting responses on the command line, the curl cheat sheet covers the most common flags.