HTTP 503 Service Unavailable

5xx Server Error

5xx Server Error RFC 7231, Section 6.6.4

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

500 Internal Server Error 502 Bad Gateway 504 Gateway Timeout 429 Too Many Requests

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.

All 5xx Codes All Status Codes

Last updated: 21 Jun 2026

Blog