# 500 Internal Server Error

> https://http-status.org/docs/500

**Family:** 5xx Server Error

## Rationale

Generic server fault; unexpected condition.

## In Plain Terms

Something broke on our end! It's not your fault - our server had a problem and couldn't handle your request.

## Description

The HTTP 500 Internal Server Error status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

## Server Perspective

### Usage
- 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

### Implementation
- 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

### Common Headers
- No status-specific header is required; include a request ID or tracing header when your API supports incident debugging

### Body
- Include a concise generic error payload with a stable error code and correlation ID when available

### 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)

## Client Perspective

### Pitfalls
- Do not assume a 500 means the client payload is invalid
- Do not blindly retry unsafe writes without idempotency protection

## Examples

### Database connection failure

The server failed processing the request and returned a stable error payload. Including a correlation ID in the body helps operators trace the incident in server logs.

**Request:**
```
GET https://api.example.test/api/users
```

**Response:**
```
500 Internal Server Error
Content-Type: application/json

{
  "error": "internal_server_error"
}
```

## Related Codes

- [501 Not Implemented](/docs/501.md)
- [502 Bad Gateway](/docs/502.md)
- [503 Service Unavailable](/docs/503.md)
- [504 Gateway Timeout](/docs/504.md)