Skip to content

503 Service Unavailable

The server cannot handle the request right now, usually because it is overloaded or down for maintenance. Try again later.

What 503 Service Unavailable means

503 is for temporary conditions. The server can send Retry-After with a number of seconds or a date to say when it expects to be back.

It is the right status for planned maintenance pages. Search engines treat a short 503 as temporary and keep the page, while a maintenance page served with 200 could end up indexed.

Common causes

  • Planned maintenance or a deploy in progress.
  • More traffic than the available servers or workers can handle.
  • No healthy backends left behind a load balancer because the app is failing health checks.
  • A dependency such as the database is down, and the app reports itself unavailable.

How to fix 503 Service Unavailable

  1. As a visitor, wait and retry, and check the site's status page.
  2. As a client, honour Retry-After and back off instead of retrying in a tight loop.
  3. As the owner, check health checks, autoscaling, worker limits (PHP-FPM pm.max_children, Gunicorn workers) and CPU and memory usage.
  4. Serve maintenance pages with 503 and a Retry-After header.

Headers that go with it

  • Retry-After

Example response

HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: text/plain; charset=utf-8

503 Service Unavailable

How to check for a 503 response

cURL

# Print only the status code
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/

JavaScript (Node.js)

const res = await fetch("https://example.com/");
if (res.status === 503) {
  console.log(res.status, res.statusText);
}

Python

import requests

res = requests.get("https://example.com/")
if res.status_code == 503:
    print(res.status_code, res.reason)

Go

res, err := http.Get("https://example.com/")
if err != nil {
	log.Fatal(err)
}
defer res.Body.Close()
if res.StatusCode == 503 {
	fmt.Println(res.Status)
}

Specification

503 Service Unavailable is defined in RFC 9110, section 15.6.4.

  • 502

    Bad Gateway

    A server acting as a gateway or proxy got an invalid response, or no usable response, from the upstream server behind it.

  • 504

    Gateway Timeout

    A gateway or proxy waited too long for a response from the upstream server and gave up before the page was ready.

  • 429

    Too Many Requests

    You sent too many requests in a short time and hit a rate limit. Wait, then retry, ideally after the Retry-After time.

← all 63 HTTP status codes

Type to search posts, tools and projects.

Keyboard shortcuts

Search+Kor/
Go to homegthenh
Go to bloggthenb
Go to projectsgthenp
Go to timelinegthent
Show this help?
Close search or helpesc