Skip to main content
apiguide.dev

HTTP 503 — Service Unavailable

The server is temporarily down or overloaded. The client should retry.

Status CodeHTTP 503
CategoryServer Error (5xx)
API Error Subtypes1 error schema
HTTP Headers1 header

What does HTTP status code 503 mean?

The 503 Service Unavailable status code indicates that the server is temporarily unable to process the request due to planned maintenance or severe overload.

When to use it in APIs

Use during deployments, maintenance windows, or when database connection pools are exhausted. Always include a Retry-After header.

How it compares to other codes

  • 429 Too Many Requests: Triggered when a specific client exceeds their quota. 503 is returned when the system itself is overloaded globally.

Specific API Error Types for 503

Service Unavailable

Custom error schema (Slug: service-unavailable)

View reference →

Associated HTTP Headers

Retry-After

Tells the client how long to wait before making a follow-up request.

View reference →

Related HTTP Status Codes

HTTP 429 — Too Many Requests

The user has sent too many requests in a given amount of time.

View reference →

Sponsors

Support the project →