Skip to content

503 Service Unavailable

The server is temporarily unable to handle the request, typically because it is overloaded or down for maintenance.

Status

HTTP/1.1 503 Service Unavailable

Details

  • Category: 5xx
  • Status: Standard. Registered with IANA and defined by a current standards-track RFC.
  • Specification: RFC 9110 §15.6.4
  • Cacheable: Only with explicit cache headers
  • Response body: Allowed
  • Retry: Retry after a delay

503 says the condition is temporary and expected to clear. It is the correct code for planned maintenance, for shedding load under pressure, and for a service whose dependencies are unavailable. Retry-After tells the client when to come back and, during maintenance, tells search engines not to deindex the page.

It is also the standard response from anti-bot and DDoS protection layers while they evaluate traffic, which is why automated clients meet it during challenge flows.

Note: Send Retry-After during maintenance. Without it, crawlers can treat a long outage as content removal rather than a temporary condition.

Headers

  • Retry-After: Seconds or an HTTP date. Important for both clients and crawlers during maintenance windows.

Common causes

  • Planned maintenance with the application deliberately serving a maintenance page.
  • Overload: worker pool exhausted, queue full, or an autoscaler still catching up.
  • A critical dependency such as a database or cache is unavailable.
  • Load shedding or a circuit breaker refusing new work to protect the system.
  • A protection layer holding the request while it evaluates the client.

How to fix it

As the client

  • Honour Retry-After and back off. Retrying hard against an overloaded server makes recovery slower.
  • Add jitter to retries so a fleet of clients does not return in a synchronized wave.
  • Reduce concurrency rather than only spacing retries, since 503 under load is usually about parallelism.

As the server

  • Always send Retry-After during maintenance. Without it, crawlers may treat the outage as content removal.
  • Serve a static maintenance page from the edge so the origin is not doing work while it is meant to be resting.
  • Scale the bottleneck rather than the whole stack, and check queue depth before adding capacity.

Examples

Planned maintenance

A request during a maintenance window:

HTTP request

GET / HTTP/1.1
Host: www.example.com

Retry-After tells both clients and crawlers that the condition is temporary:

HTTP response

HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/html; charset=utf-8

Notes for proxy users

A 503 that appears only for automated traffic and clears for a browser is usually a protection layer rather than an outage. Lower concurrency, add delay between requests, and distribute across more addresses before assuming the site is down.

Specifications

See also