Not Found Errors

title: "Not Found Errors — Handling 404 Responses with Clarity" description: "404 Not Found errors indicate the requested resource doesn't exist, with responses that include the missing resource identifier and possible correct alternatives." date: 2026-06-28 lastmod: 2026-06-28 weight: 17 tags: [apis, error-handling] }

404 Not Found errors occur when a client requests a resource that doesn't exist, including mistyped IDs, deleted resources, or incorrect endpoint paths.

What You'll Learn

• Structuring 404 error responses
• Differentiating missing resource from wrong endpoint
• Handling bulk operations with partial not-found

Why It Matters

Clear 404 errors help developers fix URL mistakes quickly. Ambiguous 404s waste debugging time.

Code Examples

// Not found error responses
{
  "error": "NOT_FOUND",
  "message": "User with ID '999' not found",
  "resource_type": "user",
  "resource_id": "999",
  "suggestion": "Check the user ID or list users at GET /users"
}

// Bulk operation with partial not-found
{
  "error": "PARTIAL_NOT_FOUND",
  "message": "Some resources were not found",
  "not_found_ids": ["user-456", "user-789"],
  "found_count": 3
}

// Wrong endpoint
{
  "error": "NOT_FOUND",
  "message": "No endpoint matches GET /user",
  "suggestion": "Did you mean GET /users?"
}

# Not found error handler
class NotFoundError(Exception):
    def __init__(self, resource_type, resource_id):
        self.resource_type = resource_type
        self.resource_id = resource_id
        super().__init__(f"{resource_type} '{resource_id}' not found")

@app.errorhandler(NotFoundError)
def handle_not_found(error):
    return jsonify({
        "error": "NOT_FOUND",
        "message": str(error),
        "resource_type": error.resource_type,
        "resource_id": error.resource_id
    }), 404

Common Mistakes

1. Returning Empty 404 Bodies

An empty 404 gives developers no hint about what was wrong.

2. Hiding 404 Behind Generic Messages

"Resource not found" without the ID forces clients to guess.

3. Not Distinguishing Type from Instance

Distinguish "no such endpoint" (wrong URL) from "resource not found" (wrong ID).

4. No Suggestions

If the endpoint has typos, suggest the correct URL.

5. Inconsistent ID Format Reference

Use the same ID format in errors as the client sent.

Practice Questions

1. What status code indicates a resource was not found?
2. What information should a 404 response include?
3. How do you differentiate wrong endpoint from wrong ID?
4. Why include the requested ID in the error?
5. How should bulk operations handle partial not-found?

Answers:

1. 404 Not Found.
2. Resource type, ID, human message, and possible suggestions.
3. Different error messages: "No endpoint matches" vs "Resource not found".
4. So the developer can see exactly which ID was wrong.
5. Return 200 with the found items and a partial error listing missing IDs.

Challenge: Design a 404 handling system that automatically detects typos and suggests correct endpoint names (e.g., /users for /user).

FAQ