Service Unavailable

# Quick Definition

The server is currently unable to handle the request due to temporary overloading or scheduled maintenance. This implies the condition is temporary and the server will be available again after some time. Unlike a 500 error, a 503 explicitly signals that the outage is expected to resolve.

# When Does a 503 Error Occur?

A 503 Service Unavailable error is returned during planned maintenance windows, traffic spikes beyond server capacity, application pool recycling, or when the server is deliberately taken offline. It's the "polite" server error -- the server knows it can't help right now, but it expects to recover.

This is the correct status code for maintenance pages and is often accompanied by a Retry-After header that tells clients when to come back.

# Common Causes

• Server undergoing planned maintenance or updates
• Traffic spike exceeding server capacity (viral content, flash sales)
• Application pool or worker process recycling (IIS, PHP-FPM restarts)
• Rate limiting at the server level rejecting excess requests
• Database connection pool exhausted -- all connections in use
• Server deliberately taken offline for updates or configuration changes
• Auto-scaling not provisioning new instances fast enough for demand
• DDoS attack overwhelming server resources

# How to Fix a 503 Error

1. Check if maintenance is scheduled -- Look for maintenance mode flags, deployment scripts, or team announcements. If maintenance is planned, the 503 is intentional.
2. Review server load -- Run top, htop, or uptime to see if the server is overwhelmed. High CPU or memory usage points to capacity issues.
3. Check application pool status -- For IIS, check Application Pool health. For PHP-FPM, check systemctl status php-fpm and worker process counts.
4. Verify database connection pool -- Check if the database connection pool is exhausted. Increase max_connections or optimize queries to release connections faster.
5. Scale up server resources -- Add more instances behind the load balancer or increase the current server's CPU/RAM to handle the load.
6. Implement or adjust rate limiting -- Use rate limiting to prevent any single client from overwhelming the server while still serving most users.
7. Check for DDoS patterns -- Review access logs for unusual traffic patterns. Implement WAF rules or use a DDoS protection service if under attack.
8. Use Retry-After header -- Include a Retry-After header in your 503 response so clients and search engines know when to come back.

# HTTP Example

GET /api/data HTTP/1.1
Host: example.com
Accept: application/json

HTTP/1.1 503 Service Unavailable
Content-Type: application/json
Retry-After: 300
Date: Thu, 20 Feb 2026 12:00:00 GMT

{
  "error": "Service Unavailable",
  "message": "Server is under maintenance. Please retry after 300 seconds."
}

# Related Status Codes

# Frequently Asked Questions