HTTP 503 Service Unavailable
HTTP 503 Service Unavailable is the "down for maintenance" or "overloaded" signal. Unlike 500 (an unexpected failure), 503 often indicates a known, managed state: the server is aware it cannot handle requests right now. This distinction matters for operations: a 500 spike is an incident; a 503 during a maintenance window is expected.
The Retry-After header is what makes 503 useful in practice. With Retry-After, clients and crawlers know exactly when to come back. Without it, they have to guess. During planned maintenance, always serve 503 with a specific Retry-After timestamp — this prevents crawlers from deindexing your pages (Google will revisit before marking pages unreachable) and allows monitoring systems to suppress alerts during known maintenance.
Quick reference
| Code | 503 |
|---|---|
| Name | Service Unavailable |
| Category | 5xx server errors |
| Specification | RFC 9110 |
| IANA status | Assigned |
| When to use | Use 503 for: intentional maintenance windows, overload shedding when the server cannot handle more requests, circuit breaker tripping on a failing dependency. Always include Retry-After when you know the recovery time. For rate limiting a specific client, use 429 instead. |
| Client behavior | Retry after the time specified in Retry-After. If no Retry-After, use exponential backoff. Implement circuit breaker logic to stop sending requests to an endpoint that has been returning 503 repeatedly. |
| Caching | May be cached if Retry-After is present, but this is unusual. Generally not cached. |
Common causes
- Server overload — too many concurrent requests
- Scheduled maintenance downtime
- Rate limiter or circuit breaker engaged
- Dependency service (database, cache) is down
How to fix it
- Implement retry logic with the Retry-After header
- Scale infrastructure if overload is the cause
- Return 503 with a Retry-After header during planned maintenance
- Set up health checks and auto-recovery for dependencies
Example exchange
GET /example HTTP/1.1 Host: errorlookup.com HTTP/1.1 503 Service Unavailable
When you see this in production
Operational 503 use cases:
- Maintenance mode: return 503 + Retry-After during planned downtime
- Load shedding: return 503 when request queue depth exceeds a threshold
- Dependency failures: circuit breaker returns 503 when upstream dependency health check fails
- Rolling deploys: briefly return 503 during instance restart (handled by load balancer health checks)
In Kubernetes, a pod returning 503 during liveness probe failure triggers pod restart.
What developers usually do next
- Handling 503:
- 1. Read the Retry-After header and wait before retrying
- 2. Implement circuit breaker logic for 503-heavy dependencies
- 3. If 503 is unexpected: check server load metrics, database connection pool exhaustion, memory pressure
- 4. If 503 appears during deploys: verify rolling deploy configuration is waiting for health checks before sending traffic
- 5. For maintenance windows: pre-communicate Retry-After time to stakeholders
When NOT to use this code
Do not use 503 for client-specific rate limiting (use 429). Do not return 503 without Retry-After when you know the recovery time — the header is what makes 503 operationally useful. Do not use 503 for application errors (use 500). Do not confuse 503 with 502 (upstream bad response) or 504 (upstream timeout).
Related status codes
HTTP 502 Bad Gateway · HTTP 504 Gateway Timeout · HTTP 429 Too Many Requests
Behind Cloudflare or Nginx?
When your origin is overloaded or temporarily down, the CDN/proxy layer may surface 503 as vendor-specific codes:
Comparisons
HTTP 503 vs 421 · HTTP 503 vs 429 · HTTP 503 vs 500 · HTTP 503 vs 502 · HTTP 503 vs 429 · HTTP 503 vs 504
Frequently asked questions
How should I handle 503 in my application?
Implement retry logic with exponential backoff, respecting the Retry-After header if present. For critical operations, implement a circuit breaker pattern to prevent cascading failures.
Standards reference
This definition is derived from the IANA HTTP Status Code Registry and RFC 9110. Human-readable operational guidance by ErrorLookup. · HTTP 503 quick reference →