---
title: "HTTP 503 Service Unavailable: meaning and fixes"
url: https://proxy.wiki/glossary/http-status-503/
type: Glossary Term
author: "proxy.wiki editorial"
published: 2026-10-21
updated: 2026-10-21
site: proxy.wiki
topics: ["Proxy fundamentals"]
license: CC BY 4.0; quote freely with attribution to https://proxy.wiki/
---

# HTTP 503 Service Unavailable: meaning and fixes

> 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](https://www.rfc-editor.org/rfc/rfc9110#section-15.6.4) describes overload and scheduled maintenance, and says the response may include [Retry-After](/glossary/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](/glossary/http-status-504/) explains the timeout case, and [Retry-After](/glossary/retry-after/) covers the header format. The [403 vs 407 vs 429 guide](/guides/403-vs-407-vs-429/) 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](https://www.rfc-editor.org/rfc/rfc9110#section-15.6.4)
2. [RFC 9110 section 10.2.3: Retry-After](https://www.rfc-editor.org/rfc/rfc9110#section-10.2.3)
