# 501 Not Implemented

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

**Family:** 5xx Server Error

## Rationale

Server does not support the requested method or required functionality.

## In Plain Terms

Our server doesn't know how to do what you asked. This feature hasn't been built yet.

## Description

The HTTP 501 Not Implemented status code indicates that the server does not support the functionality required to fulfill the request.

## Server Perspective

### Usage
- Return 501 when the method or capability is unimplemented across the server, not merely disallowed on one resource
- Use it for truly unsupported functionality, not for temporary outages or ordinary application exceptions
- Server does not implement the request method at all
- A mandatory capability required by the request is not supported anywhere on this server
- Protocol behavior is recognized but the implementation is not available

### Implementation
- Confirm the method or feature is not implemented before returning 501; if the resource-specific method is known but disallowed, return 405 with Allow instead
- Explain the unsupported capability in a safe machine-readable error body when possible

### Common Headers
- No status-specific header is required; unlike 405, 501 does not require an Allow header
- 501 is heuristically cacheable by default; set Cache-Control: no-store or equivalent if the method may become supported in future.

### Body
- A body is optional but helpful; identify the unsupported method or capability and any supported alternative if one exists

### Pitfalls
- Do not return 501 for GET or HEAD, which compliant servers are expected to support
- Do not use 501 when the method is understood but blocked on a particular resource
- Method not allowed on specific resource (use 405 Method Not Allowed)
- Unexpected internal failures while trying to process a supported feature (use 500 Internal Server Error)
- Version negotiation failures (use 505 HTTP Version Not Supported)
- Resource doesn't exist (use 404 Not Found)
- Temporary maintenance or overload (use 503 Service Unavailable)

## Client Perspective

### Pitfalls
- Do not treat 501 like a transient server outage
- Do not assume changing authentication or payload shape will fix the request

## Examples

### Unsupported HTTP method

Server doesn't implement the TRACE method

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

**Response:**
```
501 Not Implemented
Content-Type: application/json

{
  "error": "not_implemented"
}
```

## Related Codes

- [405 Method Not Allowed](/docs/405.md)
- [505 HTTP Version Not Supported](/docs/505.md)