UUID Studio

503 Service Unavailable

The server is temporarily unable to handle the request - overloaded or down for maintenance.

What 503 means

503 is the deliberate refusal: the server is working, and is choosing not to serve this request because it is overloaded, in maintenance, or missing a dependency it needs. That intentionality is what makes it more useful than 500 - it says the failure is understood, not unexpected.

It is the only 5xx that carries a natural companion header. Retry-After tells clients when to come back, and sending it is the difference between clients backing off in an orderly way and a retry storm that keeps the service down. During an overload event this matters a great deal.

The other thing worth doing is shedding load deliberately. A server that accepts every request and times out serves everyone badly; one that returns 503 quickly above a concurrency threshold keeps working for the requests it does accept. Returning 503 fast is a feature, not a failure.

For planned maintenance, a 503 with Retry-After is also the SEO-correct answer - search engines treat it as temporary and do not deindex, where a 404 or a 200 error page would cause real damage.

Common causes of a 503

  • Overload - more concurrent requests than the server can handle.
  • Planned maintenance.
  • A required dependency unavailable: database, cache, message broker, downstream API.
  • A circuit breaker open after repeated downstream failures.
  • Autoscaling not yet caught up with a traffic spike.
  • A connection or thread pool exhausted, so new work cannot be accepted.
  • Kubernetes readiness probes failing, so no pods are receiving traffic.

How to fix a 503

  • Send Retry-After - without it, clients guess and generally make the overload worse.
  • Shed load deliberately above a concurrency threshold rather than accepting everything and timing out.
  • Check dependency health, and whether a circuit breaker is open.
  • For planned maintenance, use 503 with Retry-After rather than a 200 error page or a 404.
  • Review readiness probe configuration if this appeared after a deployment.

Headers this status expects

  • Retry-After - seconds or an HTTP date. The single most valuable header on a 503.

Should a client retry?

Explicitly temporary, so retry - honouring Retry-After if present, otherwise exponential backoff with jitter.

FAQ

What is the difference between 500 and 503?
500 means something failed unexpectedly. 503 means the server is deliberately declining work because it is overloaded, in maintenance, or missing a dependency. 503 is a much better signal, and it can carry Retry-After.
What should I return during planned maintenance?
503 with a Retry-After header. Search engines treat it as temporary and will not deindex the site, where a 404 or a 200 error page can do lasting damage.
503 or 429?
429 when a specific client has exceeded its quota. 503 when the server as a whole cannot cope, regardless of who is asking. Both should send Retry-After.
Is returning 503 quickly better than being slow?
Yes. A server that accepts everything and times out serves all requests badly; one that sheds load above a threshold keeps working for the requests it accepts. Fast, deliberate 503s are a load-shedding strategy.

Often confused with