Error guide

503 Service Unavailable

The server is deliberately refusing to serve right now — overloaded, in maintenance, or with nothing healthy to route to.

A 503 Service Unavailable says the server cannot handle the request at the moment and expects the condition to be temporary. Unlike a 502, it is usually deliberate: something decided not to serve, rather than something failing unexpectedly.

There are three quite different situations behind it. Maintenance mode, where an operator deliberately switched serving off. Overload, where the server or its queue is full and is shedding requests to stay alive. And an empty backend pool, where a load balancer has no healthy instances left to route to and answers 503 because there is nowhere to send anything.

A 503 may include a Retry-After header, and it is worth sending one. It tells well-behaved clients and crawlers when to come back, and during planned maintenance it is the difference between search engines treating your site as temporarily unavailable and treating it as broken.

Common causes

  • Maintenance mode enabled deliberately, sometimes and forgotten afterwards.
  • Every backend instance failing its health check, leaving the load balancer with nothing to route to.
  • The application's request queue or worker pool full and shedding load.
  • An autoscaling group that has not scaled up yet, or has hit its ceiling.
  • A dependency failure causing every instance to report unhealthy at once.
  • A rate limiter or DDoS protection layer answering 503 rather than 429.

How to diagnose it

  1. Determine which layer is answering: the load balancer, the web server, or the application. Their 503s mean different things.
  2. Check the health of the backend pool — how many instances are in service, and why the others were removed.
  3. Confirm maintenance mode is off; a forgotten maintenance flag is a surprisingly common cause of a long 503.
  4. Look at queue depth and worker saturation if the cause is overload rather than absence.
  5. Check whether backends are failing their health check for a reason unrelated to serving traffic, such as a dependency the check touches.

Whose fault is it? The server's side

Server-side, and often deliberate. A 503 during announced maintenance is correct behaviour; a 503 from overload is a capacity incident; a 503 from an empty backend pool is an outage.

What monitoring sees

A 503 fails a check like any other 5xx. This is the code most often produced by planned work, which is what per-monitor mutes and scheduled maintenance are for in Uptimely: a mute stops incidents being declared for a fixed window while probing, status and uptime history continue, and scheduled maintenance additionally announces the window on your status page and to subscribers.

Related error guides

Terms used on this page

Questions

Should I return 503 during planned maintenance?

Yes, with a Retry-After header. It tells crawlers the outage is temporary and stops them treating the pages as broken, and it is the honest status for a service that is deliberately not serving.

What is the difference between 503 and 502?

A 503 is a deliberate refusal — overloaded, in maintenance, or no healthy backends. A 502 is an unexpected failure to get a usable response from the upstream. Refusing versus failing.

One of the Uptimely HTTP and network error guides, written for the person who operates the server rather than the one refreshing the page. Something here read wrong to you? Email support@getuptimely.com.