404

Not Found

4xx Client Error

ELI5

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

Server perspective

Use 404 when the server cannot find the target resource and is not making a stronger permanence claim.

When to use

•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

How to respond

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

Headers to consider

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

Response body

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

Server-side 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)

Examples

Accessing non-existent user

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

Response:

404 Not Found

# Headers
Content-Type: application/json

# Body
{
  "error": "not_found"
}

No user exists with ID 99999 in the database

Typo in URL path

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

Response:

404 Not Found

# Headers
Content-Type: application/json

# Body
{
  "error": "not_found"
}

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

References

Related Status Codes

Gone

This used to exist here, but it's been permanently removed and won't be coming back.

Forbidden

I know who you are, but you're not allowed to do this. You don't have permission for this action.