404 or 410 for a deleted resource?

410 Gone if it definitely existed and is permanently removed - it tells clients and search engines to stop requesting it. 404 if you do not know or do not want to say. Crawlers drop 410 URLs faster than 404s.

Should I return 404 instead of 403 for resources a user cannot access?

It is a reasonable security choice, because a 403 confirms the resource exists and lets an attacker enumerate. The cost is harder debugging, so log the actual reason server-side.

Why does my API return 404 for a route I know exists?

Usually a trailing slash, a case mismatch, or a proxy rewriting the path before your application sees it. Log the exact path the application receives, which is often not the one the client sent.

404 Not Found

The server has no resource at that URL.

Class 4xx · Client error
Retry Do not retry

What 404 means

404 means the server found nothing at the requested URL and says nothing about whether it ever existed or might exist later. It is the most familiar status code and one of the most overloaded, because it is used both for genuinely absent resources and as a deliberate substitute for 403.

That substitution is a legitimate security practice: returning 404 rather than 403 for resources the caller may not access means an attacker cannot enumerate what exists by observing which URLs give which error. If you do this, be aware it makes your own debugging harder, and log the real reason server-side.

For an API, the distinction worth drawing is between a missing route and a missing resource. GET /usres/123 (a typo in the path) and GET /users/999999 (a valid route, no such user) are very different problems, and returning the same bare 404 for both makes them indistinguishable. Say which in the body.

410 Gone exists for the case where a resource definitely existed and has been permanently removed. It tells clients and crawlers to stop asking, where a 404 invites them to keep trying.

Common causes of a 404

A genuine typo in the path, or a stale link.
A valid route with an identifier that does not exist.
A trailing-slash mismatch where the router treats /users and /users/ differently.
Case sensitivity - most path routing is case-sensitive even where the host filesystem is not.
A resource deleted since the client last saw it.
A deliberate 404 masking a 403 for a resource the caller cannot access.
A proxy or rewrite rule stripping a path prefix before it reaches the application.

How to fix a 404

Distinguish 'no such route' from 'no such resource' in the response body.
Check trailing slashes and case in the path.
For a permanently removed resource, return 410 Gone so crawlers stop requesting it.
Log the real reason server-side when you return 404 in place of 403.

Should a client retry?

Nothing at that URL. Retrying is pointless unless you believe the resource is about to appear - and if it might, 202 or 404 with a Retry-After is a clearer signal.

FAQ

404 or 410 for a deleted resource?: 410 Gone if it definitely existed and is permanently removed - it tells clients and search engines to stop requesting it. 404 if you do not know or do not want to say. Crawlers drop 410 URLs faster than 404s.
Should I return 404 instead of 403 for resources a user cannot access?: It is a reasonable security choice, because a 403 confirms the resource exists and lets an attacker enumerate. The cost is harder debugging, so log the actual reason server-side.
Why does my API return 404 for a route I know exists?: Usually a trailing slash, a case mismatch, or a proxy rewriting the path before your application sees it. Log the exact path the application receives, which is often not the one the client sent.

Often confused with

403 Forbidden The server understood the request and is refusing it - authentication will not help.
410 Gone The resource existed and has been permanently removed.