503 Service Unavailable: what it means and how to fix it
A 503 Service Unavailable means the server is reachable but cannot take the request right now. It is overloaded, starting, scaling, in maintenance, or has no healthy instance to route to. Unlike a 500, a 503 says the problem is temporary.
What causes a 503
- No healthy instance. Every instance behind the load balancer is failing its health check.
- Starting or scaled to zero. The service is still booting, or was put to sleep when idle and is waking up.
- Too much traffic for the instances running, so the platform or the app sheds load.
- A dependency is down. Some apps answer 503 on purpose when the database or a cache they need is unreachable.
- Maintenance mode, switched on for a migration or a deploy.
How long does a 503 last?
As long as the cause. A cold start or a deploy clears in seconds to minutes; an overload lasts until traffic drops or the service scales. Servers can send a Retry-After header with a 503 to say when to try again, and well-behaved clients and crawlers respect it.
How to fix a 503
- Check the health checks. Find out whether the instances are failing them, and why: a slow boot, a wrong path or a dependency.
- Check the instance count. Look for a deploy or scale event in progress, or a service scaled to zero.
- Look for saturation. CPU or memory at the limit means you need more instances or a faster app.
- Read the logs for a database, cache or API the app cannot reach.
503 on app platforms
App platforms return 503 when no instance is ready to serve: while a service starts, after it fails its health check, or while it wakes from sleep on plans that stop idle services. A 503 that appears only on the first request after a quiet period is a cold start. One that persists is a service that never became healthy; see 5xx errors for how to trace it.