HTTP 503 Service Unavailable – Free, Online, Private

What HTTP 503 means

503 says the server is not ready to handle the request, often because it is overloaded or down for maintenance. It is temporary. Retry-After should be sent when you know how long. Unlike 500, 503 means you decided not to do the work, or you are unable to take it, not that you tried and threw. Clients may retry after the delay. A 503 without Retry-After leaves the backoff to the client.

503 Service Unavailable belongs to the 5xx server error class. Clients that only look at the class will group it with its neighbors. Clients that care about the exact code should use the narrower rule on this page, because the class is only the first digit.

When you see HTTP 503

When you see HTTP 503 Service Unavailable, stop on that exact status line. 503 Service Unavailable means the server cannot handle the request right now. The trace that usually produces it: A deploy took the process out of rotation and a straggler received 503. The 5xx server error class only tells you the first digit. A neighbor in that class is a different fault, and the fix on this page does not transfer to it.

Return 503 when you are shedding load, deploying, or otherwise unavailable, and you want clients to come back. Send Retry-After. Use 429 if only this client is over a limit. Use 500 if you attempted the request and crashed. Do not return 503 for a single bad row in a database if the rest of the service is fine. That is a 500 on that request.

How to fix HTTP 503

To fix HTTP 503, change the condition that made the server choose Service Unavailable. Honor Retry-After. Back off if it is absent. Do not open more connections. A browser can show the message. An API client should surface a temporary error, not a validation error. Yes, after Retry-After, with jitter. Stop after a handful of attempts and report the outage. If the log line is a different code, leave this page. The mix-up people make with 503 is this one: 500 is an unexpected failure. 429 is one client's quota. 502 is a bad upstream. 503 is 'not now' from the server that would otherwise do the work.

• Load shedding rejected work and Retry-After told clients when to return.
• A client ignored Retry-After and retried at once, adding load.
• A dependency outage was mapped to 503 for every route, including routes that did not need the dependency.

An access log that only stores 503 is not enough to tell these apart. Keep the method, the path, and a request id. Do not keep the Authorization header or a request body that might be a token. The status explains the outcome. It is not a place to echo secrets back to the client either.

Example response

HTTP 503 Service UnavailableHTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/plain

Try again soon.

Retry-After: 120 asks for two minutes of quiet. Maintenance pages should use 503, not 200, so clients and monitors do not treat the page as healthy. A 200 maintenance page is how uptime checks go green during an outage.

What the client should do

Honor Retry-After. Back off if it is absent. Do not open more connections. A browser can show the message. An API client should surface a temporary error, not a validation error.

A 503 may be cached only as an error under careful rules. Prefer not to cache it, so recovery is visible immediately. Never cache it as a successful representation.

Yes, after Retry-After, with jitter. Stop after a handful of attempts and report the outage.

Codes people confuse with HTTP 503

500 is an unexpected failure. 429 is one client's quota. 502 is a bad upstream. 503 is 'not now' from the server that would otherwise do the work.