HTTP 503 Service Unavailable
5xx Server Error
- Home
- HTTP Status Codes
- 5xx
- 503
What is HTTP 503 Service Unavailable?
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 which will likely be alleviated after some delay. The response should include a Retry-After header indicating when the service is expected to be available again.
Common Use Cases
- Server maintenance mode
- Traffic overload or spikes
- Application deployment in progress
- Resource exhaustion (connections, threads)
Usage Example
During a scheduled maintenance window, configure your application to return 503 Service Unavailable with a Retry-After header indicating when the service will resume. For traffic spikes, use 503 with a short Retry-After to tell clients to back off and retry later, preventing further overload.
// Laravel - maintenance mode (php artisan down)
// Automatically returns 503 with Retry-After
// Custom 503 for traffic spikes
return response()->json([
'error' => 'Service unavailable',
'retry_after_seconds' => 30,
], 503)
->header('Retry-After', 30);Related Status Codes
Common Mistakes
Mistake: Using 503 without a Retry-After header
Fix: Always include a Retry-After header in 503 responses so clients know when to retry. Without it, clients may retry immediately or give up entirely.
Mistake: Using 503 for permanent unavailability
Fix: Use 503 only for temporary conditions. If the service is permanently unavailable, use a 404 or 410 Gone with appropriate messaging.
Mistake: Not distinguishing 503 (overloaded) from 429 (rate limited)
Fix: Use 503 when the server is overloaded or under maintenance. Use 429 when the specific client exceeded their request quota. 503 affects all clients; 429 affects only the specific client.