Back to error codes
ERROR 503
Service Unavailable
HTTP Error
The server is temporarily unable to handle the request due to overload or maintenance.
Root Cause
The server is overloaded, in maintenance mode, or a dependency (database, cache) is unavailable.
How to Fix
Return a Retry-After header indicating when the service will be available. Implement circuit breakers and graceful degradation.
Quick Summary
503 means the server is temporarily unavailable. Return a Retry-After header. Implement circuit breakers and graceful degradation. Use for planned maintenance and overload scenarios.
Key Takeaways
Key Takeaways
- Return Retry-After header to tell clients when to retry
- Use for planned maintenance windows
- Implement circuit breakers to return 503 when dependencies are down
- Graceful degradation: return cached data or a simplified response instead of 503 when possible
Use Cases
When to use it
- Planned maintenance window
- Server overloaded
- Database is down
Watch out
Common Mistakes
- Not returning Retry-After, clients do not know when to retry
- Returning 503 without implementing graceful degradation, consider returning cached data instead
FAQ
503 Service Unavailable, Frequently Asked
How do I implement a maintenance mode that returns 503?
In Nginx: return 503; with a custom error page. In Next.js: check a maintenance flag in middleware and return a 503 response.
Still having issues?
Check your network logs or use our developer tools to inspect headers, decode tokens, or validate your requests.