503 Service Unavailable

Description

The 503 Service Unavailable status code indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance. This status code implies that the server is expected to become available again after some delay.

Common scenarios where a 503 Service Unavailable might occur include:

Server is under maintenance
Server is overloaded with too many requests
Server resources (CPU, memory, connections) are exhausted
Rate limiting or throttling is being applied
A service is being deployed or restarted
Backend services required by the server are unavailable

Unlike a 500 Internal Server Error, which indicates an unexpected condition, a 503 response explicitly communicates that the server is temporarily unavailable but will likely be available again in the future.

Syntax

HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: application/json
Content-Length: 183

{
  "error": {
    "code": 503,
    "message": "Service Unavailable",
    "details": "The server is temporarily unable to handle the request due to maintenance or overload."
  }
}

Examples

Example 1: Scheduled Maintenance

A server is undergoing scheduled maintenance and is temporarily unavailable.

Request:

GET /api/users HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 503 Service Unavailable
Retry-After: 3600
Content-Type: application/json
Content-Length: 226

{
  "error": {
    "code": 503,
    "message": "Service Unavailable",
    "details": "The server is currently undergoing scheduled maintenance and will be available again in approximately 60 minutes."
  }
}

Example 2: Server Overload

The server is receiving more requests than it can handle and is temporarily rejecting new requests.

Request:

POST /api/process-image HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Length: 1024

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="image"; filename="large-image.jpg"
Content-Type: image/jpeg

[binary data]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response:

HTTP/1.1 503 Service Unavailable
Retry-After: 30
Content-Type: application/json
Content-Length: 208

{
  "error": {
    "code": 503,
    "message": "Service Unavailable",
    "details": "The server is currently experiencing high load. Please try again in 30 seconds or reduce request frequency."
  }
}

Example 3: Dependent Service Unavailable

A web application depends on a backend service that is currently unavailable.

Request:

GET /api/dashboard HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response:

HTTP/1.1 503 Service Unavailable
Retry-After: 60
Content-Type: application/json
Content-Length: 211

{
  "error": {
    "code": 503,
    "message": "Service Unavailable",
    "details": "One or more backend services required to fulfill this request are currently unavailable. Please try again later."
  }
}

Summary

The 503 Service Unavailable status code indicates that the server is temporarily unable to handle the request due to a temporary overload or maintenance. It communicates to clients that the unavailability is expected to be temporary and provides guidance on when to retry.

Key points about 503 Service Unavailable:

It indicates a temporary condition, unlike 501 Not Implemented which is permanent
It often includes a Retry-After header suggesting when to retry the request
It's appropriate for planned maintenance, server overload, or temporary resource exhaustion
It's preferable to a generic 500 error when the server knows it's temporarily unavailable
Clients should respect the Retry-After header if provided
It can be used proactively during deployments or maintenance windows
Load balancers and API gateways often generate this status when backend services are unavailable
Unlike 502 Bad Gateway, it doesn't necessarily imply a problem with communication between servers