What a 503 means
A website, load balancer, CDN or reverse proxy can send a 503. A forward proxy you configured can also return one when its own service is unavailable. Unlike a connection failure, a 503 is a complete HTTP response from something in the request path.
HTTP/1.1 503 Service Unavailable
Retry-After: 120Retry-After: 120 asks the client to wait 120 seconds before trying again. The header can also contain a date, but it isn’t always present and doesn’t guarantee the next request will succeed.
Common causes
- Traffic overload. The service has more active requests than its servers or connection pools can handle.
- Scheduled maintenance. The operator has temporarily taken the application or an API endpoint offline.
- No healthy upstream servers. A gateway is running, but the application servers behind it are unavailable.
- Protective throttling. Some systems use 503 instead of 429 when traffic exceeds their capacity or configured limits.
- Proxy service trouble. Your configured proxy may be overloaded or unable to reach its upstream network.
How to fix a 503
- Check the response headers. Look for
Retry-After,Server,Viaand CDN-specific headers to identify the sender. - Wait before retrying. Honor
Retry-After. If it is missing, use exponential backoff with random jitter and a retry limit. - Reduce request pressure. Lower concurrency and requests per second. Repeated immediate retries can keep an overloaded service unavailable for longer.
- Test the request path. If permitted, compare a direct request with one through the proxy. This helps show whether the website or proxy generated the response.
- Retry safe operations only. Repeating a
GETis usually safe. Automatically retrying aPOSTcan create duplicate orders, messages or other actions unless the API supports idempotency.
503 vs 502 vs 504 vs 429
| Code | Sent by | Meaning |
|---|---|---|
| 503 Service Unavailable | Server or intermediary | Service can’t handle the request now |
| 502 Bad Gateway | Gateway | Invalid response from upstream |
| 504 Gateway Timeout | Gateway | Upstream response took too long |
| 429 Too Many Requests | Website or intermediary | This client sent too many requests |
FAQ
Is a 503 error temporary?
Usually. HTTP defines 503 for temporary unavailability, but the sender may not provide a recovery time. Persistent 503 responses can indicate a failed service or incorrect server configuration.
Is a 503 caused by my proxy?
It can be. Check the response headers and compare the same request through another permitted route. If only the proxied request fails, the proxy or its path to the website may be unavailable.
How long should I wait before retrying a 503?
Use the Retry-After value when present. Otherwise, start with a short delay, increase it after each failure and stop after a limited number of attempts.