Skip to content
5xx · server errorSent by App | Proxy | CDN

503Service Unavailable

The server is up but is refusing work for now, because it is overloaded or in maintenance.

How you get a 503

The app is alive but every worker is busy. It refuses the new request straight away and the app sends 503, often with a Retry-After header. The proxy and CDN pass it along untouched.

Who sends itApp · Proxy · CDN

  1. Browser
  2. CDN
  3. Proxy
  4. App
  5. DB

Whichever box decides it cannot take the request: typically the app when it sheds load, or the load balancer when it has no healthy backend to send to. Which one depends on your setup.

In short

What a 503 Service Unavailable means

A 503 Service Unavailable is a deliberate answer. Something on the server side is alive, looked at the request, and decided not to do it right now: the application is at its concurrency limit, a rate limiter rejected it, the site is in maintenance mode, or a load balancer has no healthy backend left. It is the only one of the common 5xx codes that says the problem is temporary, and it can carry a Retry-After header telling clients how long to wait. Because the work is refused before it starts, a 503 comes back quickly and the request has typically not been processed. The mistake to avoid is retrying at once. Every client doing that sends the struggling server more traffic than it had before, and the overload feeds itself.

Common causes of a 503

  1. 1The app is shedding load: a concurrency limit, full queue or circuit breaker rejected the request.

    How to check: Look for Retry-After on the response and for limit messages in the app's own log.

    curl -sI https://example.com/ | grep -i retry-after
  2. 2The load balancer has no backend to send to (none registered, or all removed by health checks).

    How to check: Check target or server health in the load balancer. HAProxy logs the missing server by name.

    <NOSRV> … 503
  3. 3A rate or connection limit in the proxy. nginx's limit_req and limit_conn reject with 503 unless configured otherwise.

    How to check: Search the nginx error log for the limiter.

    limiting requests, excess: … by zone
  4. 4Kubernetes: the Service has no ready pods, so the ingress has nowhere to route.

    How to check: List the endpoints behind the Service. An empty list means no pod passed its readiness probe.

    kubectl get endpoints <service>
  5. 5Planned maintenance: the site is deliberately serving a holding page.

    How to check: Ask whoever deployed last, and check for a maintenance flag in the proxy or app configuration.

Retry or not?

Safe to retry with backoff · After waiting

A 503 says the condition is temporary. If there is a Retry-After header, wait at least that long. If not, back off exponentially with jitter. Retrying immediately adds load to a server that has just told you it has too much.

Headers that matter

Retry-After
How long to wait before trying again, as a number of seconds or an HTTP date. Optional, but the best signal a client can get.
Server / Via
Shows whether the app or a box in front of it made the decision.
Cache-Control
Maintenance pages should not be stored by caches. Send no-store so the outage does not outlive itself.

In the real world

RFC vs real deployments

RFC 9110 ties 503 to temporary overload or scheduled maintenance. In practice it is also what several load balancers send when they have no backend at all: HAProxy when no server is available, and an AWS Application Load Balancer when a target group has no registered targets. Envoy goes further and uses 503 for a refused upstream connection, which nginx would report as 502. The RFC also points out that a server is not obliged to send 503 when overloaded. Some simply refuse the connection, and the client sees no status code at all.

Seen in a real outage

A 503 only helps if clients listen to it. In the AWS us-east-1 outage of December 2021, a bug stopped internal clients from backing off, and their retries kept the network congested long after the original trigger had gone.

Your turn

Which code is it?

At peak traffic an API starts failing. Each error returns in about 3 ms, carries “Retry-After: 5”, and the app's own log says “concurrency limit reached”. Which code is it?

Often confused with

503 questions

Who sends a 503 Service Unavailable?
Whichever server decides it cannot take the request. Typically that is the application when it is shedding load or in maintenance, or a load balancer that has no healthy backend. Check the Server header to see which.
Should I retry a 503?
Yes, but not immediately. Wait for the time given in the Retry-After header if there is one, otherwise back off exponentially with some randomness so that clients do not all return at the same moment.
What is the difference between 500 and 503?
A 500 means the server tried to handle the request and something unexpected broke. A 503 means the server declined to try, for a reason it expects to pass, such as overload or maintenance.

Practise this in the DNS / HTTP track

Two-minute animated lessons, then boss fights from real outages. Free, no account needed.

Start the track