503 Service Unavailable

The 503 (Service Unavailable) status code indicates a temporary problem with the server that will likely improve after some delay; for example, scheduled or unscheduled maintenance, or general overload.

Writing responses (servers)

Use this status code for things like scheduled maintenance, when the request queue is too long, or when the server is above CPU or I/O capacity.

For alleviating very high capacity, the server may simply decide to refuse connections. Servers may have to balance this option against the possibility that clients do not implement exponential backoff, and immediately try to establish new connections.

Servers should use the Retry-After response header with a sensible value. For an overload condition, values of a few seconds are sensible. If down for maintenance, values of 60-300 seconds are sensible. Think about the tasks that your users are likely trying to run, when picking a value.

The response headers may include a Link header with rel=status pointing to a service status page, that provides uptime, availability, and maintenance information.

The response body should also include a link to the uptime or status page for the service, if any; and a description of a nature of the outage.

Most load balancers can be configured to return this status code, to avoid forwarding requests to application servers while they are being worked on.

If the request contains a long payload, consider terminating the request to avoid consuming network resources.

See also: 507 (Insufficient Storage)

If the server can serve most requests, but it cannot accept incoming payloads because it has no storage to do so, see 507 (Insufficient Storage).

Reading responses (clients)

Clients may retry the request after the duration specified by the Retry-After response header; or else retry the request after a short period (e.g. one second), with exponential backoff for subsequent failed requests.

If there is a response body, show it to the user, so they may make a decision about how to modify the request. For example, maybe there is important information about the scheduled maintenance window that the users can act on.

Overview table

Name

503

Message

503 Service Unavailable

Description

Indicates a temporary problem with the server that will likely improve after a delay

Specification

RFC 7231: HTTP/1.1 Semantics and Content §6.6.3. 503 Service Unavailable

Example

HTTP/1.0 503 Service Unavailable
Retry-After: 3600
Content-Type: text/plain
Link: <http://status.example.com/>;rel=status

Our servers are currently down for scheduled maintenance.
Maintenance begins Tue, 15 Nov 1994 08:12:31 GMT
Estimated outage time: 6 hours
Service status page: http://status.example.com/