MockFoxAdvertise

HTTP 503 Service Unavailable

Updated Free mock REST & WebSocket APIs

HTTP 503 Service Unavailable — The server is temporarily unable to handle the request (overload or maintenance).

Class
5xx Server Error
Defined in
RFC 9110 §15.6.4
Official
Yes (IANA registry)
Cacheable by default
No (unless Cache-Control/Expires say so)
Safe to retry
Yes, after a delay (respect Retry-After)

Try it: get a real 503 response

Our test endpoint answers every request with 503 Service Unavailable.

curl -i https://mockfox.dev/api/status/503

Use it in tests, health-check monitors or to see how your client handles a 503. Add ?delay=2000 to slow it down.

What does HTTP 503 mean?

503 Service Unavailable means the server is currently unable to handle the request because of a temporary overload or scheduled maintenance, which will likely be alleviated after some delay. The server may send Retry-After to say when to try again.

It's the right status for planned downtime and for load shedding. Search engines treat it as temporary: Googlebot backs off and retries rather than de-indexing pages (as long as the outage doesn't last days).

When is 503 used?

  • Maintenance mode during upgrades and migrations (WordPress shows "Briefly unavailable for scheduled maintenance").
  • Too many concurrent requests; worker pool or connection pool exhausted.
  • No healthy targets behind a load balancer (AWS ALB, Kubernetes service with no ready pods).
  • Platform limits: Heroku H-codes, serverless concurrency limits, or a host suspending a site.

Common causes of a 503

  • A traffic spike beyond capacity.
  • The application is restarting or failing health checks.
  • A dependency (database, cache) is down and the app reports itself unavailable.
  • A deliberate maintenance page or circuit breaker.

How to fix 503 Service Unavailable

If you're visiting the site

  1. Wait and retry later — the site expects to be back.
  2. Check the service's status page or social media for maintenance notices.

If you run the site or API (developers)

  1. Send Retry-After with maintenance responses and keep them short and non-cached.
  2. Scale out or add queueing/caching to absorb spikes; shed load gracefully instead of crashing.
  3. Check load-balancer target health and readiness probes.
  4. If WordPress is stuck in maintenance mode, delete the .maintenance file in the site root.

Returning or handling 503: server examples

nginx

# Maintenance mode: touch /var/www/maintenance.on to enable
server {
    if (-f /var/www/maintenance.on) { return 503; }
    error_page 503 @maintenance;
    location @maintenance {
        add_header Retry-After 600 always;
        rewrite ^ /maintenance.html break;
        root /var/www/static;
    }
}

Express

let maintenance = process.env.MAINTENANCE === "1";
app.use((req, res, next) =>
  maintenance
    ? res.status(503).set("Retry-After", "600").json({ error: "maintenance" })
    : next());

Next.js

// app/api/example/route.ts (Next.js App Router)
export async function GET() {
  if (!(await db.isHealthy()))
    return Response.json({ error: "unavailable" }, { status: 503, headers: { "Retry-After": "30" } });
  return Response.json(await getData());
}

Example 503 response

HTTP/1.1 503 Service Unavailable
Retry-After: 600
Content-Type: text/html; charset=utf-8
Cache-Control: no-store

<h1>We'll be back soon</h1><p>Scheduled maintenance — about 10 minutes.</p>

Related status codes

Related tools

Frequently asked questions

How long does a 503 error last?

It depends on the cause: seconds for overload, minutes to hours for maintenance. A Retry-After header, if present, gives the server's estimate.

Is 503 good for SEO during maintenance?

Yes — it's the recommended status for planned downtime. Google treats it as temporary for a day or two. Returning 200 with a maintenance page, or 404, can damage indexing.

What's the difference between 503 and 502?

503 says the service itself is temporarily unavailable. 502 says a proxy got an invalid response from the server behind it.