404 - Not Found
HTTP 404 Not Found means the server has no current representation for the requested URI at this path, version, tenant, or lifecycle state.
Last reviewed: April 12, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Not Found Mean?
Treat 404 as a lookup failure. The useful tuple is path, identifier, and scope: the route the client called, the resource key it used, and the environment, tenant, or region where that key was resolved.
Common Causes
- -Client calls an old path or API version after a route migration, so the origin has no handler or canonical representation at that URI.
- -Resource ID, slug, or composite key is stale because a cache, merge, migration, or background sync produced an old identifier.
- -Tenant, region, shard, or project scope is wrong, so the resource exists somewhere else but not in the context of this request.
- -Rewrite or redirect rules map the request to the wrong upstream path, creating deterministic misses on only some routes.
- -The resource was deleted, archived, or intentionally hidden, and the system now returns 404 for that lifecycle state.
How to Fix Not Found
- 1Capture the full requested path, identifier, tenant or region context, and request ID before debugging caches or backend logic.
- 2Verify the resource exists in the same environment and scope the failing request used.
- 3Check route versioning, rewrites, and canonical links before assuming data loss or application bugs.
- 4Correct the path, ID, or scope and replay the exact request against the canonical resource location.
Step-by-Step Diagnosis for Not Found
- 1Capture the full URI, route params, tenant or region context, and request ID from the 404 path.
- 2Verify the resource exists, was not soft-deleted, and is addressable in the same environment and namespace as the failing request.
- 3Trace the identifier back to its source to find stale caches, merged records, or old links that are generating invalid lookups.
- 4Inspect routing, rewrite, redirect, and API version rules to confirm the request is reaching the intended handler.
- 5Determine whether this route intentionally masks access with 404 instead of 403 so teams do not debug the wrong layer.
- 6Compare against a working example of the same resource type to isolate path drift, scope drift, or lifecycle drift.
Seen in Production
- -Client calls
/api/v2/orders/8472, but production still serves that resource only on/api/v1/orders/8472, so only upgraded clients succeed. - -Support links work for tenant A and fail for tenant B because the UI copied the right object ID into the wrong tenant context.
- -A merged record now lives under a new slug, while search results and emails still point users to the retired slug and generate clean 404s.
Route and Identity Reconciliation
- -Validate the canonical path, API version, and identifier format before blaming storage or search indexes (example:
/v2/users/{id}caller is hitting a service that still exposes/v1). - -Correlate lifecycle events such as merge, archive, delete, move, or replication lag with the timestamp of the 404 request.
Wrong Fix to Avoid
- -Do not immediately purge every cache if the real issue is a wrong route, wrong tenant, or wrong ID coming from the caller.
- -Do not convert intentional security masking from 404 to 403 without confirming the product and security teams actually want that behavior.
Implementation Examples
GET /api/v2/orders/8472 HTTP/1.1
Host: api.example.com
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_5bb104
{
"error": "Not Found",
"path": "/api/v2/orders/8472",
"requestId": "req_5bb104"
}curl -i https://api.example.com/api/v1/orders/8472 \
-H "Accept: application/json"Seen in Production
Client keeps calling an old API version after route migration
Frequency: common
Example: Mobile apps continue using /v1/orders/{id} or /v2/orders/{id} after backend changed the canonical path and only some clients updated.
Fix: Publish compatibility redirects or alias routes, then sunset old paths with telemetry-backed deprecation windows.
Wrong tenant or region context makes a real object look missing
Frequency: common
Example: An order exists in eu-west, but the request is routed to us-east or the wrong tenant context and returns 404.
Fix: Propagate the correct tenant and region identifiers end to end and test lookups with real scoped identities.
Security masking intentionally hides foreign resources
Frequency: medium
Example: Multi-tenant API returns 404 for foreign-tenant object IDs to avoid confirming object existence.
Fix: Document the masking behavior, monitor it deliberately, and keep support workflows aligned so teams do not misclassify it as random data loss.
Debugging Tools
- -Access logs with full path, tenant, and request ID
- -Route-table, rewrite, and redirect tracing
- -Primary-database and index existence checks in the same scope
- -Broken-link and stale-slug scanners
- -Version and region routing diagnostics
How to Verify the Fix
- -Replay the exact failing URI with the corrected path, ID, and scope and confirm the route no longer returns 404.
- -Verify downstream clients, deep links, and background jobs now resolve the same canonical resource.
- -Check logs for remaining stale-link or stale-identifier traffic after the fix ships.
- -If the resource was intentionally retired, verify redirects or 410 behavior are now consistent with product intent.
How to Prevent Recurrence
- -Generate URLs and resource IDs from shared canonical helpers instead of string-building them in each client.
- -Add post-deploy crawl checks for critical routes across multiple tenants, versions, and regions.
- -Instrument delete, merge, archive, and move flows so they emit redirects, tombstones, or telemetry instead of silent stale links.
Pro Tip
- -run link-integrity and API-smoke jobs with real scoped identities, because single-tenant synthetic checks miss many production 404s.
Decision Support
Compare Guide
403 Forbidden vs 404 Not Found: When to Hide Resources
Use 403 for explicit access denial, or 404 to conceal resource existence when security policy requires reducing endpoint and object enumeration risk.
Compare Guide
404 Not Found vs 410 Gone: Missing vs Permanent Removal
Learn when to return 404 (missing or temporary absence) versus 410 (intentional permanent removal), including redirect and cache implications.
Playbook
Resource State Playbook (404 / 410 / ResourceNotFound)
Use this playbook to separate temporary missing-resource lookups from permanent removals, then fix scope, lifecycle, and identifier drift safely.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.