Developer Toolbox
About

500 Internal Server Error

Something went wrong on the server, and it has no more specific code for it.1 It nearly always means an unhandled exception or a broken configuration, and the details are in the server's logs, not in the response.

  • Class 5xx server error
  • Retry idempotent requests only
Open Timestamp Converter Turn the Unix timestamps in your server logs into dates.

Common causes

  • An unhandled exception: a null reference, a failed database query, a timeout inside the app that nothing caught.
  • A configuration error: a missing environment variable, a wrong file permission, a syntax error in .htaccess.
  • An input the code didn't expect: an empty body, a field of another type, a character outside ASCII where the code assumed ASCII.
  • A dependency returned an error, and the code passed it on as a 500.

How to fix it

  • Look at the server log around the time of the request. Most frameworks log the stack trace, and a request ID in the response (X-Request-Id) makes the entry easy to find.
  • Reproduce with the exact request, same body and same headers: the bug is often in an input the tests never covered.
  • As a client, retry only idempotent requests (GET, PUT, DELETE),2 with backoff. Retrying a POST can create a duplicate unless the API supports idempotency keys.
  • As a server, answer bad input with a 4xx instead of letting it crash into a 500, and keep stack traces out of production responses.

500 or 502?

500 comes from the application itself. 502 comes from a proxy or load balancer in front of it that got no valid response at all, because the app crashed, restarted or closed the connection.3

Example

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json
X-Request-Id: 7f3c9a2e-5b1d-4c8e-9f6a-2d4b8e1c0a57

{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Quote the request id when reporting it."
}

Sources

  1. 1 RFC 9110, HTTP Semantics, section 15.6.1. rfc-editor.org ↩︎
  2. 2 RFC 9110, HTTP Semantics, section 9.2.2. rfc-editor.org ↩︎
  3. 3 RFC 9110, HTTP Semantics, section 15.6.3. rfc-editor.org ↩︎