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 is currently unable to handle the request because of a temporary overload or scheduled maintenance.
Specification
Registered in the IANA HTTP Status Code Registry as Service Unavailable. Defined in RFC 9110, Section 15.6.4.
What it means
HTTP 503 Service Unavailable means the server cannot handle the request right now because it is overloaded or down for maintenance. The condition should pass after a delay. The server MAY send Retry-After to say when to try again. RFC 9110 notes that a server does not have to use 503 when overloaded; some refuse the connection instead.
When to use it
- Return 503 during planned maintenance, with Retry-After set to the expected end.
- Return 503 when the service sheds load because it is at capacity.
- Return 503 from health checks when an instance should be taken out of a load balancer pool.
- Use 429 instead when a specific client exceeded its own rate limit.
Common causes
- Planned maintenance or a deploy in progress.
- Too much traffic for the available workers, connections, or memory.
- A load balancer with no healthy backends to send traffic to.
- A required dependency, such as the database, is down and the service fails fast.
Headers involved
- Retry-After gives the expected wait as seconds or an HTTP date.
- Cache-Control: no-store keeps a maintenance page from being cached after the service comes back.
How to fix it
- As a client, wait for Retry-After or back off exponentially before retrying.
- As an operator, check the load balancer for healthy targets and the service for resource exhaustion.
- Add capacity, or shed lower-priority traffic first.
Examples
Planned maintenance
GET /api/orders HTTP/1.1
Host: api.example.com
HTTP/1.1 503 Service Unavailable
Retry-After: 600
Cache-Control: no-store
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/maintenance",
"title": "Scheduled maintenance",
"status": 503,
"detail": "Back by 02:30 UTC."
}Common mistakes
- Serving a maintenance page with 200. Search engines may index it, and monitors report everything is fine.
- Returning 503 for a single client's rate limit. That is 429.
- Leaving a site on 503 for days. If the 503 lasts, search engines may start dropping its URLs from the index.
Developer notes
503 with Retry-After is the right response for a short maintenance window. For search engines, it says "come back later" instead of "this page changed".
Questions
What does HTTP 503 Service Unavailable mean?
HTTP 503 means the server is temporarily unable to handle the request because of overload or maintenance.
Should a maintenance page return 503?
Yes. Return 503 with Retry-After so clients and search engines know the outage is temporary.
What is the difference between 503 and 429?
503 means the service is unavailable to everyone. 429 means one client exceeded its rate limit.
See also
Header and content rules
What RFC 9110 says about a 503 response, quoted from the RFC. The 5xx class rules also apply.
- MAY (server; Retry-After): Send Retry-After with a suggested wait. Optional. Table row
The server MAY send a Retry-After header field (Section 10.2.3) to suggest an appropriate amount of time for the client to wait before retrying the request. RFC 9110 §15.6.4
The same rule is in the response obligations table and its JSON.