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.
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.
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?
What is 503 versus 502?
Sources
Also covered in
- Cause 5: the proxy could not reach the destination (502, 503, 504)in Proxy error: what each message means and how to fix it