# 404 Not Found

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

**Family:** 4xx Client Error

## Rationale

Resource does not exist or its existence is intentionally not exposed.

## In Plain Terms

The thing you're looking for doesn't exist here. It's like knocking on a door and nobody's home.

## Description

The HTTP 404 Not Found status code indicates that the server can't find the requested resource.

## Server Perspective

### Usage
- Return 404 for unknown routes, missing resources, or intentionally hidden existence
- Use 404 when you do not want to distinguish between never existed, hidden, or unknown
- Requested resource doesn't exist
- Resource was deleted and you don't want to reveal it existed
- Resource exists but you intentionally want to avoid confirming it (security masking instead of 403)
- Invalid API endpoints or routes

### Implementation
- Keep the error body simple and avoid leaking sensitive resource details
- Prefer 410 when you know the resource existed and has been permanently removed

### Common Headers
- No status-specific header is required; still send normal HTTP metadata such as Content-Type, caching, or tracing headers when they help the client.

### Body
- A short explanation is optional, but many APIs simply return a generic not-found error payload

### Pitfalls
- Do not use 404 for permission failures unless hiding existence is intentional
- Do not use 404 when a redirect or explicit deprecation path would better help clients recover
- Server errors (use 5xx codes)
- Authentication required (use 401 Unauthorized)
- Resource exists but access forbidden (use 403 Forbidden)
- Resource moved permanently (use 301 Moved Permanently)

## Client Perspective

### Pitfalls
- Do not assume 404 always means the resource never existed

## Examples

### Accessing non-existent user

No user exists with ID 99999 in the database

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

**Response:**
```
404 Not Found
Content-Type: application/json

{
  "error": "not_found"
}
```

### Typo in URL path

The endpoint '/api/usres' doesn't exist (should be '/api/users')

**Request:**
```
GET https://api.example.test/api/usres/123
```

**Response:**
```
404 Not Found
Content-Type: application/json

{
  "error": "not_found"
}
```

## Related Codes

- [410 Gone](/docs/410.md)
- [403 Forbidden](/docs/403.md)