HTTP 404 Not Found: Complete Guide for REST APIs

What is HTTP 404 Not Found?

HTTP 404 Not Found is a client error response status code indicating that the server cannot find the requested resource. Defined in RFC 9110, 404 is one of the most common HTTP status codes and is part of the 4xx Client Error class — meaning the request itself is the problem, not the server.

Important distinction: a 404 does not mean the resource never existed. It means the resource cannot be found at the requested URL at this time. If a resource existed and was permanently removed, the correct code is 410 Gone. Many APIs return 404 for deleted resources as an acceptable simplification, but 410 provides more accurate semantics.

The 404 response says: "I understood your request, I looked for what you asked for, and I couldn't find it."

404 Response Body Best Practices

Never return an empty body with a 404 status code. Clients need context to handle the error correctly. Always return a structured JSON body:

// Standard 404 response — always return a JSON body:
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User with ID 12345 was not found.",
    "resource": "users",
    "id": "12345"
  }
}

What to Include

• code: A machine-readable string constant. Clients use this to handle specific error types programmatically. Use resource-specific codes like USER_NOT_FOUND, ORDER_NOT_FOUND rather than the generic RESOURCE_NOT_FOUND when possible — it improves debuggability.
• message: A human-readable description that identifies what was being looked for. Include the resource type and the ID that was searched for: "User with ID 12345 was not found."
• resource and id (optional): Structured fields for programmatic access to the resource type and requested ID.

What Not to Include

• Database error messages or query details
• Stack traces or internal implementation details
• Information that reveals whether a resource ever existed (if you want to prevent information disclosure)
• Suggestions about which IDs do exist

404 vs Other 4xx Status Codes

Real-World 404 Examples in REST APIs

Two complete request/response examples showing how 404s should look in practice:

Example 1: User Not Found

GET /api/v1/users/99999
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-ID: req_7f3a9b2c

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "No user found with ID 99999",
    "resource": "users",
    "id": "99999"
  }
}

Example 2: Nested Resource Not Found

GET /api/v1/orders/abc-123/items/xyz-456
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-ID: req_4d8e1f5a

{
  "error": {
    "code": "ORDER_ITEM_NOT_FOUND",
    "message": "Item xyz-456 not found in order abc-123",
    "resource": "order_items",
    "id": "xyz-456",
    "parent_resource": "orders",
    "parent_id": "abc-123"
  }
}

Notice that both examples:

• Use a resource-specific error code (USER_NOT_FOUND, ORDER_ITEM_NOT_FOUND) rather than a generic code
• Include the resource type and ID in the message for human readability
• Return Content-Type: application/json — never return a 404 with HTML body when the client expects JSON
• Include a request ID for tracing (best practice for all API responses)

For broader status code coverage, see the HTTP Status Codes guide.

Related Topics