5xx Server Errors — Handling Server Failures

In this tutorial, you will learn about 5xx server errors. We cover key concepts, practical examples, and best practices to help you master this topic.

5xx status codes indicate the server failed to Process a valid request due to unexpected errors, upstream failures, or capacity issues.

Code Reference

500 Internal Server Error: Unexpected server failure. Should not happen in normal operation. 502 Bad Gateway: Upstream service returned invalid response. 503 Service Unavailable: Server overloaded or under maintenance. 504 Gateway Timeout: Upstream service timed out.

Examples

// Global 500 handler
app.use((err, req, res, next) => {
  console.error(`[${req.id}] ${err.message}`, err.stack);
  res.status(500).json({
    status: 500,
    error: "internal_error",
    message: "An unexpected error occurred",
    requestId: req.id,
    timestamp: new Date().toISOString()
  });
});

Common Mistakes

1. Exposing internals — Returning stack traces or database errors.
2. No request ID — Cannot correlate with server logs.
3. No error logging — Server errors that are not logged are invisible.
4. Retry-After missing on 503 — Clients need to know when to retry.

Practice Questions

1. When should you use 502 vs 503?
2. Why should server errors hide internal details?
3. What header should accompany 503 responses?

What's Next

In the next lesson, you will learn error response formats.