Example HTTP Response
HTTP/1.1 503 Service Unavailable
Retry-After: 3600- Server maintenance
- Server overloaded
- Temporary outage
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.
Ready-to-use code for returning this HTTP status in your application:
// 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);- 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