503 Service Unavailable

503

Service Unavailable

⚙️

Example HTTP Response

HTTP Response

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

Common Causes

Server maintenance
Server overloaded
Temporary outage

Technical Details

What does this mean?

BRB! The server is taking a coffee break or being pampered with maintenance. Please hold!

Technical Definition

The server is not ready to handle the request, often due to maintenance or overloading.

RFC Says

"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. The server MAY send a Retry-After header field to suggest an appropriate amount of time for the client to wait before retrying the request."

Plain English:

503 means 'I'm temporarily unavailable, try again later.' Use this during maintenance windows, when you're overloaded, or when a critical dependency is down. Unlike 500, which says 'something broke,' 503 says 'everything is working, but I can't serve you right now.' Always include a Retry-After header when possible.

Common Misinterpretation

Use 503 for temporary conditions that you expect to resolve automatically. Include a Retry-After header. Don't use 503 for permanent shutdowns (use 410) or for bugs/crashes (use 500). Good use cases: database connection pool exhausted, rate limiting at infrastructure level, deployment in progress.

View RFC Documentation

Code Snippets

Ready-to-use code for returning this HTTP status in your application:

Node.js

// Express.js
app.get('/example', (req, res) => {
  res.status(503).json({
    error: 'Service Unavailable',
    message: 'Your error message here'
  });
});

// Native HTTP
const http = require('http');

http.createServer((req, res) => {
  res.writeHead(503, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({
    error: 'Service Unavailable',
    message: 'Your error message here'
  }));
}).listen(3000);

When to Use This Code

Server is temporarily overloaded and can't handle requests
Planned maintenance window
Include Retry-After header to indicate when to try again
Use 429 for rate limiting individual clients

SEO Handling

Indexing

503 is the recommended status for planned maintenance. Google honors Retry-After headers and preserves indexing during short outages.

Crawler Behavior

Crawlers respect Retry-After headers and postpone recrawling. This is the SEO-friendly way to handle maintenance.

Canonical URL Notes

During maintenance, return 503 with Retry-After rather than showing a 200 maintenance page, which could get indexed.

Google Notes

Google recommends 503 + Retry-After for maintenance. Extended 503s (days) may eventually cause pages to be dropped from the index.

Google Search Documentation →

From the Blog

Understanding HTTP 503 Service Unavailable: Planned Downtime, Overload, and Graceful Failure
A deep dive into HTTP 503 — when to return it, why Retry-After matters, how to ship maintenance windows without trashing your SEO, and the differences between 503, 500, 502, and 429.
10 min read

Related Status Codes

💥500Internal Server Error 🌉502Bad Gateway ⌛504Gateway Timeout 🚦429Too Many Requests

Commonly Confused With

💥500Internal Server Error 🌉502Bad Gateway

503 Service Unavailable FAQ

What causes a 503 Service Unavailable error?

Server maintenance. Server overloaded. Temporary outage.

When should I use 503 Service Unavailable?

Server is temporarily overloaded and can't handle requests. Planned maintenance window. Include Retry-After header to indicate when to try again. Use 429 for rate limiting individual clients.

// Express.js app.get('/example', (req, res) => { res.status(503).json({ error: 'Service Unavailable', message: 'Your error message here' }); }); // Native HTTP const http = require('http'); http.createServer((req, res) => { res.writeHead(503, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ error: 'Service Unavailable', message: 'Your error message here' })); }).listen(3000);

503 Service Unavailable FAQ

What causes a 503 Service Unavailable error?

Server maintenance. Server overloaded. Temporary outage.

When should I use 503 Service Unavailable?

Server is temporarily overloaded and can't handle requests. Planned maintenance window. Include Retry-After header to indicate when to try again. Use 429 for rate limiting individual clients.