# 503 Service Unavailable

> https://http-status.org/docs/503

**Family:** 5xx Server Error

## Rationale

Server not ready to handle the request (maintenance or overload).

## In Plain Terms

Our service is temporarily down for maintenance or overloaded. Please try again later.

## Description

The HTTP 503 Service Unavailable status code indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

## Server Perspective

### Usage
- Return 503 for planned maintenance windows, brownouts, dependency saturation, or temporary capacity protection
- Use it when recovery is expected, even if the exact time is uncertain
- Scheduled maintenance downtime
- Server overload or high traffic
- Database maintenance
- Temporary service outages
- CPU, connection pool, or memory capacity exhaustion protecting the service from cascading failure

### Implementation
- Send Retry-After when you can estimate when the service should be available again
- Serve a clear maintenance or overload response and make sure health checks, load balancers, and autoscaling signals understand the degraded state

### Common Headers
- Retry-After is recommended when you know an estimated recovery time
- 503 responses should not be cached without explicit cache controls; set Cache-Control: no-store unless you intentionally want an outage page cached.

### Body
- Include a user-friendly explanation and, for APIs, a stable error code plus any retry guidance or status-page link

### Pitfalls
- Do not use 503 for caller-specific throttling when 429 Too Many Requests is the clearer signal
- Do not hide known upstream protocol failures behind 503 when 502 or 504 is more accurate
- Permanent service shutdown (use 410 Gone)
- Bad upstream responses (use 502 Bad Gateway)
- Client rate limiting (use 429 Too Many Requests)

## Client Perspective

### Pitfalls
- Do not treat a cached 503 page as proof the outage is still active without checking cache controls
- Do not keep retrying unsafe writes without idempotency protection

## Examples

### Scheduled maintenance

Service down for maintenance, retry in 1 hour

**Request:**
```
GET https://api.example.test/api/users
```

**Response:**
```
503 Service Unavailable
Retry-After: 3600
Content-Type: application/json

{
  "error": "service_unavailable"
}
```

## Related Codes

- [429 Too Many Requests](/docs/429.md)
- [500 Internal Server Error](/docs/500.md)
- [502 Bad Gateway](/docs/502.md)
- [504 Gateway Timeout](/docs/504.md)