Internal Server Error

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
• •Unhandled exceptions in server code
• •Database connection failures
• •Configuration errors preventing processing
• •Unexpected system failures

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
• •Client request errors (use 4xx codes)
• •Unsupported functionality or methods (use 501 Not Implemented)
• •Known service unavailability (use 503 Service Unavailable)
• •Bad gateway from upstream (use 502 Bad Gateway)
• •Planned maintenance (use 503 with Retry-After)

Examples