# HTTP 503 Service Unavailable — Meaning, Causes & Fixes

> The server is temporarily unable to handle requests — overloaded or down for maintenance.

503 is the server saying 'not right now'. It's meant to be temporary: maintenance windows, deploys, overload, an exhausted dependency. Send `Retry-After` so clients and crawlers know when to come back.

Search engines treat a short 503 as a pause and keep your rankings, which makes it the right status for planned maintenance.

- Class: 5xx Server Error
- Retry: With backoff (idempotent requests only)
- Cacheable by default: no
- Defined in: [RFC 9110 §15.6.4 — 503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.4)

## Example response

```http
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: application/json
Content-Length: 31

{"error":"Service Unavailable"}
```

## Common causes

- Planned maintenance or a deploy in progress.
- Traffic spikes beyond capacity: connection pools or worker queues are full.
- No healthy backends behind a load balancer.
- Scale-to-zero platforms starting cold instances.

## How to fix it

1. During maintenance, return 503 with `Retry-After` rather than a 200 'we'll be back' page.
2. Add capacity, or shed load gracefully with queues and 429s.
3. Check the load balancer's health checks — one failing check can take every target out of service.
4. Clients: retry with backoff, respecting `Retry-After`.

## Send a 503 from your server

### Express

```
res.set("Retry-After", "120");
res.status(503).json({ error: "Service Unavailable" });
```

### Next.js route handler

```
return Response.json({ error: "Service Unavailable" }, { status: 503, headers: { "Retry-After": "120" } });
```

### Flask

```
return {"error": "Service Unavailable"}, 503, {"Retry-After": "120"}
```

### Go net/http

```
w.Header().Set("Retry-After", "120")
http.Error(w, "Service Unavailable", http.StatusServiceUnavailable)
```

### nginx

```
add_header Retry-After "120" always;
return 503;
```

## FAQ

### Will a 503 hurt my SEO?

Not for a short period. Google treats 503 as temporary and comes back later. If a site returns 503 for days, pages can start dropping out of the index.

### 503 vs 500?

500: something broke unexpectedly. 503: the server knows it can't serve right now, and expects that to pass.

## Related status codes

- [502 Bad Gateway](https://www.devkult.com/http/502.md)
- [504 Gateway Timeout](https://www.devkult.com/http/504.md)
- [429 Too Many Requests](https://www.devkult.com/http/429.md)

Open the interactive page: https://www.devkult.com/http/503