TL;DR: Return 404 when the resource does not exist, or when admitting it exists would leak something. Return 403 when the caller is allowed to know the resource is there but is not permitted to access it. RFC 9110 explicitly lets a server answer 404 to hide a forbidden resource, and GitHub does exactly this for private repositories.
Side By Side
| 403 Forbidden | 404 Not Found | |
|---|---|---|
| Says | I understood the request and refuse it | I have nothing here (or will not say) |
| Confirms the resource exists | Yes | No |
| Fix for the caller | Get permission, a different role, a different IP | Fix the URL, or accept it is gone |
| Cacheable by default | No | Yes (heuristically cacheable, RFC 9110 section 15.5.5) |
| Retry after logging in | Possibly | Possibly, if the 404 was masking a 403 |
| Logged as | Permission signal worth alerting on | Mostly noise from crawlers and broken links |
The Decision
Ask whether the caller is allowed to learn that the resource exists.
- The resource really does not exist: 404.
- It exists and the caller may know that, but cannot act on it (a shared document in view-only mode, an admin button for a member): 403.
- It exists and the caller must not even learn that (another tenant’s invoice, a private repo, a user ID that could be enumerated): 404, with the same body and headers as a genuine miss.
Raw Exchanges
An invoice that belongs to another tenant. Both cases below give the attacker the same answer:
GET /api/invoices/inv_90210 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...
HTTP/1.1 404 Not Found
Content-Type: application/json
{"error": "not_found"}
The same request for inv_00000 (which truly does not exist) must return byte-identical content, otherwise the body itself is an oracle. Compare a document the user can see but not edit:
PUT /api/documents/doc_17 HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
{"title": "Q4 plan"}
HTTP/1.1 403 Forbidden
Content-Type: application/json
{"error": "forbidden", "detail": "Requires editor role on this document."}
Here the user already saw the document in a list, so denying existence would just confuse them.
GitHub As The Reference Case
GitHub’s REST API documentation states that it “uses a 404 Not Found response instead of a 403 Forbidden response to avoid confirming the existence of private repositories.” In practice:
curl -i https://api.github.com/repos/some-org/private-repo
returns 404 Not Found for an unauthenticated caller. A debugging consequence: when you hit an unexpected 404 from GitHub (or a CI token step fails with “repository not found”), check the token’s scopes, SSO authorization for the org, and repo access before assuming the URL is wrong. A genuinely missing repo and a repo you cannot see are indistinguishable by design.
Common Mistakes
Hiding existence in one place and leaking it in another. The 404 on GET /projects/{id} is undone if POST /projects returns “name already taken in another org,” or a search endpoint autocompletes the private name.
Different bodies or timing. A 404 with {"error": "no such invoice"} for a miss and {"error": "not_found"} for a masked 403 reveals the difference. Database lookups that return fast for misses and slow for permission checks add a timing signal. Keep both paths on the same code and response shape.
Using 404 everywhere and losing debuggability. Developers and support staff can no longer tell a typo from a permission bug. Log the real reason server-side with a request ID, and include that ID in the response so support can look it up.
Using 403 for unauthenticated callers. If the caller has not authenticated at all and could succeed by logging in, the answer is 401 with WWW-Authenticate. See 401 vs 403.
Returning 403 for rate limits or bot blocks without a body. 429 is the rate-limit code, and a WAF block should say which rule fired in its own page or Server signature, so people can tell it apart from an application permission error.
403 on missing S3 keys. Without s3:ListBucket, S3 answers missing objects with 403 rather than 404. It looks like a permission bug, and it is S3 hiding existence the same way. Grant list access if you want honest 404s.
Soft 404s. A “page not found” page served with 200 is neither of these; search engines treat it as a soft 404, and clients cannot tell it from success.
Quick Debug
curl -i https://example.com/admin/reports
curl -i -H 'Authorization: Bearer <token>' https://example.com/admin/reports
If the first call is 404 and the second is 200, the route exists and the 404 was masking missing authentication. Compare with the 403 reference at HTTP 403 Forbidden and HTTP 404 Not Found.