HTTP 503 Service Unavailable — Maintenance, Overload & Retry-After

When to Return 503

Return 503 during planned maintenance, when the service is overloaded, or when a critical dependency (database, cache) is unavailable. Always include Retry-After if the downtime duration is known.

Common Causes

• Scheduled maintenance window
• Database is down or unavailable
• Cache service (Redis) disconnected
• Server overloaded — connection pool exhausted
• Deployment in progress with zero-downtime issues

HTTP Response Example

HTTP/1.1 503 Service Unavailable
Retry-After: 3600
Content-Type: application/json

{"error": "Service Unavailable", "message": "Scheduled maintenance until 14:00 UTC"}

Code Examples

// Health check endpoint — return 503 if dependencies are down
app.get('/health', async (req, res) => {
  try {
    await db.ping()
    await redis.ping()
    res.json({ status: 'ok' })
  } catch {
    res.status(503).json({
      status: 'unavailable',
      error: 'Service Unavailable',
      retryAfter: 30,
    })
  }
})

// Maintenance mode middleware
app.use((req, res, next) => {
  if (process.env.MAINTENANCE_MODE === 'true') {
    return res.status(503).set('Retry-After', '3600').json({
      error: 'Service Unavailable',
      message: 'Scheduled maintenance until 14:00 UTC',
    })
  }
  next()
})

// middleware.ts — maintenance mode
export function middleware(request: NextRequest) {
  if (process.env.MAINTENANCE === 'true') {
    return new NextResponse(
      JSON.stringify({ error: 'Service Unavailable', message: 'Back soon' }),
      { status: 503, headers: { 'Retry-After': '3600', 'Content-Type': 'application/json' } }
    )
  }
}

Related Status Codes