Skip to content
5035xx · Server errorThe server has erred, or cannot perform the request. RFC 9110 §15.6

HTTP 503 Service Unavailable: meaning and fixes

Meaning

HTTP 503 Service Unavailable means the responding service cannot handle the request now. Find the layer, honour Retry-After and bound retries.

Covered in a guideUpstream refusal (503 or 502)A section of Cloudflare Error 1005: ASN banned, causes and fixes

HTTP 503 means the server is temporarily unable to handle the request: “Service Unavailable”. RFC 9110 section 15.6.4 describes overload and scheduled maintenance, and says the response may include Retry-After. The code does not prove that the whole site is down. It may come from one overloaded worker, one route or a forward proxy that cannot reach its upstream.

503 is different from 502. A 502 says a gateway received an invalid response. A 503 says the responding service is unavailable, whether because it is overloaded, administratively disabled or refusing a route. Read the body and headers before deciding whether a retry is safe.

Reproduce maintenance mode locally

This Python 3.15.0 server returns a short maintenance response and asks clients to wait 120 seconds:

from http.server import BaseHTTPRequestHandler, HTTPServer

class H(BaseHTTPRequestHandler):
    def do_GET(self):
        body = b"Down for maintenance.\n"
        self.send_response(503)
        self.send_header("Content-Type", "text/plain")
        self.send_header("Retry-After", "120")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

HTTPServer(("127.0.0.1", 8540), H).serve_forever()
$ curl -sS -i "http://127.0.0.1:8540/maint?ra=120"
HTTP/1.0 503 Service Unavailable
Server: BaseHTTP Python/3.15.0
Content-Type: text/plain
Content-Length: 22
Retry-After: 120

Down for maintenance.

The capture used curl 8.7.1. A requests 2.32.3 retry adapter waited for a documented two-second Retry-After in a second local run. With respect_retry_after_header=False, it retried immediately and still received 503. That small experiment shows why a client option can turn a planned maintenance window into a retry storm.

503 through a proxy

A forward proxy may return 503 when it cannot connect to an upstream, when its connection pool is exhausted or when an upstream route is administratively disabled. Squid’s generated page names the proxy and includes an X-Squid-Error value. If the origin’s 503 is relayed, the body and Server header usually identify the origin while Via identifies the path.

For HTTPS, a proxy can return 503 during CONNECT before TLS, or the target can return 503 after a successful CONNECT. Record both http_connect and the inner http_code. A timeout with no 503 is a different failure and belongs to the client timeout or a 504 gateway path.

Use Retry-After when it is present, then add jitter and a maximum retry count. For writes, use an idempotency key when the API supports one. For a crawler, pause the queue for the affected host instead of spawning more workers.

Causes and fixes

Cause How it shows What to change
Scheduled maintenance Body names maintenance and Retry-After gives a window Pause requests until the advertised time and use a bounded retry
Origin overload Origin headers remain, latency rises and some routes still work Lower concurrency, queue work and inspect the origin’s worker and database limits
Proxy upstream refusal Proxy identifies itself and the 503 arrives before CONNECT Check the proxy route and account, then retry only after the upstream is reachable
Connection pool exhaustion Only high-concurrency runs fail; a single request works Bound workers, close responses and increase the pool only on a service you operate
Retry storm Failures cluster immediately after each retry wave Respect Retry-After, add jitter and centralise the retry budget
Application dependency is unavailable Body identifies a database or downstream service Fix the dependency or route to a healthy one; do not hide it by rotating exits

Do not use a new proxy IP as the first response to a 503. Compare a direct request, a single alternate exit and a known-good endpoint. If only one exit fails, inspect the proxy route. If every path fails at the same time, the origin or a shared dependency is more likely. The 504 reference explains the timeout case, and Retry-After covers the header format. The 403 vs 407 vs 429 guide shows how to separate a target refusal from a proxy response.

Before retrying, classify the operation and the layer. A safe GET can wait for the advertised window, while a write needs an idempotency strategy and an owner who can confirm whether it ran. Comparing the same harmless endpoint through one direct path and one proxy keeps a maintenance response from being mistaken for a broken exit.

Frequently asked questions

Should I retry a 503?
Usually, if the operation is safe and the response indicates temporary unavailability. Honour Retry-After and bound attempts.
What is 503 versus 502?
503 means the service is unavailable. 502 means a gateway received an invalid upstream response.

Sources

  1. RFC 9110 section 15.6.4: 503 Service Unavailable
  2. RFC 9110 section 10.2.3: Retry-After

Also covered in

All terms, A to Z