500 Internal Server Error

This is an educational reference page about HTTP 500 Internal Server Error. The page itself is served as 200 OK so it can be indexed as HTTP documentation.

The server encountered an unexpected condition that prevented it from fulfilling the request.

Specification

Registered in the IANA HTTP Status Code Registry as Internal Server Error. Defined in RFC 9110, Section 15.6.1.

What it means

HTTP 500 Internal Server Error means the server hit an unexpected condition and could not complete the request. It is the catch-all server error: frameworks return it when application code throws an exception that nothing handles.

When to use it

Return 500 when the server fails for a reason that no more specific 5xx code covers.
Use 502 or 504 when a proxy or gateway got a bad or late answer from an upstream server, and 503 when the service is temporarily overloaded or in maintenance.
Use a 4xx code when the request itself is the problem. A 500 should mean the server needs fixing.

Common causes

An unhandled exception, such as a null reference or a failed type conversion.
A database error, such as a failed query or a missing migration.
A missing environment variable or bad configuration after a deploy.
A crash in a template, serializer, or plugin.

How to fix it

Check the server logs at the time of the request. Log a request ID and return it to the client so the two can be matched.
Reproduce with the same input in a non-production environment.
Roll back the latest deploy if 500s started right after it.

Examples

Unhandled error with a request ID

GET /api/invoices/2026-0193 HTTP/1.1
Host: api.example.com

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Something went wrong on our side.",
  "requestId": "req_8f2c1a"
}

Common mistakes

Returning stack traces, SQL, or file paths in the response body. Log them on the server instead.
Returning 500 for validation errors or missing records. Those are 4xx errors.
Retrying a non-idempotent request such as POST after a 500 without an idempotency key. The first attempt may have partly succeeded.

Developer notes

Clients can retry GET and other idempotent requests after a 500 with backoff. RFC 9110 says clients SHOULD NOT automatically retry non-idempotent requests unless they know the request is safe to repeat. An idempotency key is one way for an API to make a POST safe to repeat.

Questions

What does HTTP 500 Internal Server Error mean?

HTTP 500 means the server hit an unexpected condition and could not fulfill the request.

Is a 500 error my fault or the server's?

A 500 is a server-side failure. The request may have triggered it, but the server should have returned a 4xx if the request was invalid.

Should I retry after a 500?

Retry idempotent requests such as GET with backoff. Do not blindly retry POST unless the API supports idempotency keys.

Header and content rules

RFC 9110 adds no header or content rule specific to 500. The 5xx class rules also apply. See 500 in the response obligations table.

Related comparisons

500 vs 502 vs 503 vs 504 Server Errors

Related API error guide

Use RFC 9457 Problem Details to add a standard application/problem+json body without changing the meaning of HTTP 500.