500

Internal Server Error

5xx Server Error

Back to list

Server perspective

Use 500 when an unexpected server-side fault prevents the request from being fulfilled and no more specific 5xx status applies.

When to use

  • Return 500 for unhandled exceptions, broken dependencies inside the server, or unexpected runtime failures
  • Use it as a fallback for server faults that are not planned maintenance, upstream gateway errors, or unsupported functionality

How to respond

  • Log the exception with a request or correlation ID before returning the response
  • Return a stable machine-readable error code and a safe message without leaking stack traces or secrets

Headers to consider

  • No status-specific header is required; include a request ID or tracing header when your API supports incident debugging

Response body

  • Include a concise generic error payload with a stable error code and correlation ID when available

Server-side pitfalls

  • Use a more specific status such as 502, 503, or 504 when the failure mode is known and actionable
  • Do not expose internal exception messages, stack traces, SQL errors, or secret configuration in the response body

Examples

Unhandled application exception

Request:POST /api/orders with otherwise valid input
Response:500 Internal Server Error with error: internal_error and request_id

The server failed unexpectedly while processing a valid request and gives support enough metadata to investigate.

References

Related 5xx Server Error Codes