What it means
The honest answer for an unhandled exception, and it should be your least common 5xx: every 500 in a log is a bug you have not classified yet. Never leak a stack trace in the body - that is a real information-disclosure finding.
- Class
- 5xx Server error
- Defined in
- RFC 9110 §15.6.1
- Cached by default
- No
When you receive a 500
- The fault is on the server. Changing your request will not help - unless something in the request is what triggers the bug.
- Retry once if the request is idempotent. If it persists, report it with the time and any request id from the response headers.
- If it is your own server, the explanation is in its logs, not in the response.
When you send a 500
- For an error you have not handled or classified yet.
- Log the details against a request id and return the id - never the stack trace.
- Map the failures you know about to their own codes:
503for a dependency that is down,504for a timeout, a 4xx for bad input.
On the wire
HTTP/1.1 500 Internal Server Error
Content-Type: application/json
X-Request-Id: 4b1e9c2a-7f0d-4e5e-9a61-2d3c8f1b0e77
{"error": "internal", "requestId": "4b1e9c2a-7f0d-4e5e-9a61-2d3c8f1b0e77"}