503
Service Unavailable
5xx Server Error
What Does HTTP 503 Service Unavailable Mean?
HTTP 503 indicates that the server is temporarily unable to handle the request. Unlike 500 (something broke unexpectedly), 503 is often an intentional response — the server knows it cannot process requests right now and is telling you to come back later.
The 503 response should include a Retry-After header with either a number of seconds or a specific date/time when the client should try again. This helps clients implement polite retry logic instead of hammering the server during its recovery.
503 is the correct status code for planned maintenance, overload protection (shedding load to prevent a complete crash), and deployment windows. It is also what search engines want to see during maintenance — it tells crawlers that the downtime is temporary and they should not remove the page from their index.
Common Causes
- Planned maintenance: The server is intentionally offline for updates, database migrations, or infrastructure changes. A proper maintenance page returns 503 with a Retry-After header, not a 200 with a "we'll be back" page.
- Server overload: Too many concurrent requests have exhausted the server's resources (CPU maxed, memory full, all worker threads busy). The server starts rejecting new requests with 503 to protect existing connections.
- Application restart during deployment: During zero-downtime deployments, the old process is being replaced by the new one. If the transition is not seamless (e.g., no rolling restart), there is a brief window where requests get 503.
- Database or dependency unavailable: The application is running but cannot complete any request because a critical dependency (database, cache, external API) is down. The application returns 503 to signal temporary unavailability.
- Auto-scaling lag: A traffic spike hits before auto-scaling can provision new instances. The existing servers are overwhelmed and return 503 until new capacity comes online.
How to Implement and Fix 503
Nginx Maintenance Mode
# Method 1: File-based maintenance mode
# Create /var/www/maintenance.html, then:
server {
# Check for maintenance file
if (-f /var/www/maintenance_on) {
return 503;
}
error_page 503 @maintenance;
location @maintenance {
root /var/www;
rewrite ^(.*)$ /maintenance.html break;
add_header Retry-After 3600; # Come back in 1 hour
}
}
# Enable maintenance: touch /var/www/maintenance_on
# Disable maintenance: rm /var/www/maintenance_on
Express.js Circuit Breaker
// Health-aware middleware that returns 503 when dependencies are down
let dbHealthy = true;
// Monitor database health
setInterval(async () => {
try {
await db.query('SELECT 1');
dbHealthy = true;
} catch {
dbHealthy = false;
}
}, 5000);
app.use((req, res, next) => {
if (!dbHealthy) {
return res.status(503)
.set('Retry-After', '30')
.json({
error: 'Service temporarily unavailable',
message: 'The service is experiencing issues. Please try again in 30 seconds.'
});
}
next();
});
Kubernetes Readiness Probes
# Kubernetes uses readiness probes to decide when to send traffic.
# When a pod fails its readiness probe, Kubernetes removes it
# from the service load balancer, effectively producing 503 for
# that pod's portion of traffic.
apiVersion: apps/v1
kind: Deployment
spec:
template:
spec:
containers:
- name: app
readinessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 5
periodSeconds: 10
failureThreshold: 3 # 3 failures = remove from service
livenessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 15
periodSeconds: 20
Load Shedding Implementation
// Shed load when the server is too busy
const os = require('os');
app.use((req, res, next) => {
const loadAvg = os.loadavg()[0]; // 1-minute load average
const cpuCount = os.cpus().length;
// If load is above 80% of CPU capacity, start shedding
if (loadAvg > cpuCount * 0.8) {
return res.status(503)
.set('Retry-After', '10')
.json({ error: 'Server is under heavy load. Please retry.' });
}
next();
});
503 and SEO
503 is the correct HTTP status for temporary downtime. Here is why it matters for SEO:
- Google will retry: When Googlebot encounters a 503, it understands the page is temporarily unavailable and will try again later. It does not remove the page from the index.
- Do not return 200 for maintenance: Showing a maintenance page with a 200 status can cause Google to index the maintenance page content instead of the actual page content.
- Include Retry-After: Googlebot respects the Retry-After header and will wait the specified time before retrying.
- Keep downtime short: Extended 503 periods (days) may eventually cause Google to temporarily drop pages from the index. Keep planned maintenance under a few hours.
Frequently Asked Questions
What causes a 503 Service Unavailable error?
503 is caused by the server being temporarily unable to handle requests. This could be planned maintenance, server overload from too many simultaneous users, a deployment in progress, a critical dependency (database, cache) being down, or auto-scaling not yet catching up with a traffic spike. It is always temporary by definition.
How long does a 503 error last?
It depends on the cause. Deployment restarts: seconds. Maintenance windows: minutes to hours. Overload: until traffic decreases or capacity increases. Check the
Retry-After header in the response — it tells you when the server expects to be back. If there is no Retry-After header, try again in 30-60 seconds.What is the difference between 502 and 503?
502 = backend is broken. The proxy received an invalid or no response from the upstream server. 503 = server is busy or in maintenance. The server itself is choosing not to handle requests right now. 502 is usually unexpected (crash), while 503 is often intentional (maintenance, overload protection). 503 typically includes a Retry-After header; 502 rarely does.