500 Internal Server Error
The server hit an unexpected condition and cannot say anything more specific about it.
Status
HTTP/1.1 500 Internal Server Error
Details
- Category: 5xx
- Status: Standard. Registered with IANA and defined by a current standards-track RFC.
- Specification: RFC 9110 §15.6.1
- Cacheable: Only with explicit cache headers
- Response body: Allowed
- Retry: Safe to retry
500 is the generic server failure. Something threw, and the server has no better code to describe it. The cause is on the server side, so nothing the client changes about the request is guaranteed to help.
Because it is a catch-all, a 500 is only useful with a correlation identifier. Returning an opaque error page with a request id, and logging the stack trace against that id, is the difference between a solvable incident and an unreproducible one. Never return the trace itself: it leaks paths, versions, and query structure.
Note: A 500 without a correlation id is close to undiagnosable. Return a request id and log it against the stack trace, but never return the trace itself: it leaks paths, versions, and query structure.
Common causes
- An unhandled exception in application code.
- A database connection failure, exhausted pool, or query timeout.
- A configuration error, missing environment variable, or missing dependency after a deploy.
- Out of memory conditions, or a worker killed by the process supervisor.
- A misconfigured file permission or missing runtime module on the server.
How to fix it
As the client
- Retry with exponential backoff. Many 500s are transient.
- Record the correlation id from the response so support can find the exact failure.
- Reduce the request to the smallest form that still fails, which often reveals the triggering field.
As the server
- Read the application and server logs. The status code alone carries no diagnostic information.
- Return a request id in the response and log it alongside the stack trace.
- Convert known failure modes into specific codes: 503 while a dependency is down, 429 when a limit is hit, 422 when input is invalid.
- Add health checks and alerting on the 5xx rate rather than waiting for user reports.
Examples
An unhandled exception
An ordinary request that happens to hit a bug:
HTTP request
GET /api/v2/order/40213 HTTP/1.1 Host: api.example.com
The response carries a correlation id so the failure can be found in the server logs, and no stack trace:
HTTP response
HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{"error":"internal_error","request_id":"01J9X2K4M7"}