Researched guidance: How can a 404 distinguish a wrong route from deliberate resource-visibility masking?

Summary

A 404 is intentionally ambiguous: HTTP permits it for a missing route or representation and for a forbidden resource whose existence the server will not disclose. A client cannot distinguish those causes from the status alone; use documented route/method checks, safe authorization comparisons, provider-specific rules, and server-side tracing before classifying the result.

Candidate action

Treat the observed 404 as unknown rather than proof of absence. First validate the exact host, base path, route, HTTP method, path-parameter encoding, and any trailing-slash convention against the endpoint's official documentation. Then repeat the same sanitized request with a known-authorized principal and a known-nonexistent sentinel where the provider permits it, comparing only documented status/body/headers. Check authentication, token scope/permissions, tenant/resource owner, and resource visibility. For an authoritative answer, correlate the request ID with gateway/router and authorization logs: a route miss occurs before resource lookup, while a visibility mask is an authorization decision that deliberately maps an existing or potentially existing target to 404. Do not convert 404 to 403 or probe private identifiers merely to reveal existence.

Applicability

• HTTP APIs and integrations where authentication, tenancy, or resource-level visibility can affect whether a target is disclosed.
• Provider troubleshooting when the same endpoint may use 404 for both route/resource absence and unauthorized access.
• Systems with request IDs, gateway/router telemetry, or authorization-decision logs available to the operator.

Procedure

• Record the exact method, scheme/host, base path, route template, encoded path parameters, query, tenant/resource owner, auth mechanism, token class, response status/body schema, relevant headers, and provider request ID; redact tokens and secrets.
• Check the provider's official endpoint documentation for the canonical route, supported method, path encoding, host/base path, version, and trailing-slash behavior. GitHub documents that typos, an unintended trailing slash, unencoded slashes in path parameters, and even an unsupported method can yield 404.
• Check the caller context without changing authorization policy: token validity/expiry, required scopes or permissions, resource-owner or tenant match, and visibility. GitHub explicitly recommends authentication and permission checks when a private-resource request returns 404.
• Use only a safe differential test allowed by the provider: a known-public/known-authorized resource plus a known-nonexistent sentinel. A status change across principals is evidence of policy-dependent behavior, not proof of object existence; do not enumerate private IDs.
• Check intermediary behavior before blaming application routing. GitLab documents that reverse proxies which decode encoded path characters can create 404s, and its API troubleshooting page also says 404 can mean an ID was not found or the user is unauthorized.
• For S3-style HEAD operations, follow the provider's endpoint/host/bucket/key rules and do not expect the exact underlying exception from HEAD; AWS documents that HEAD errors are generic. Preserve provider-specific permission semantics rather than generalizing them to all APIs.
• Correlate the provider request ID with router/gateway and authorization logs. Only classify as a route miss when routing telemetry shows no matching route, or as visibility masking when authorization/resource policy deliberately selected a not-found response; otherwise report the cause as unknown.

Key findings

• RFC 9110 says 404 means the origin did not find a current representation or is not willing to disclose that one exists; it also permits hiding a forbidden target with 404. (S1)
• GitHub documents two distinct 404 families: private-resource requests that are not properly authenticated, and request-shape errors such as URL typos, trailing slashes, unencoded path slashes, or unsupported methods. (S2)
• GitLab explicitly states that 404 can mean an ID was not found or the user is not authorized, and documents reverse-proxy URL-decoding as another source of 404s. (S3)
• AWS S3 documents provider-specific behavior: HeadObject errors are generic, and for a missing general-purpose-bucket object the result depends on s3:ListBucket permission; endpoint, host, bucket, and key rules also matter. (S4)

Comparison

Known limitations

• RFC 9110 defines 404 as either no current representation or unwillingness to disclose one, so the response alone cannot distinguish wrong route, missing object, temporary absence, or deliberate masking.
• Provider behavior differs: GitHub intentionally uses 404 for unauthenticated/private-resource access and may also use 404 for malformed path/method cases; GitLab documents both missing IDs and unauthorized access as 404; AWS S3 HeadObject explicitly documents a permission-dependent 403/404 rule for missing objects and generic HEAD errors.
• A client-side comparison of 200 versus 404 is only diagnostic evidence and can be affected by caches, gateways, tenant policy, eventual consistency, or provider-specific error mapping; it is not an independent proof of existence.
• A 404 does not establish permanence; RFC 9110 prefers 410 only when the origin knows the condition is likely permanent. This research did not run a live request against a target deployment.

Obsolete approaches

• Treating every 404 as proof that the route or resource does not exist.
• Changing a deliberately masked 404 to 403 or adding verbose existence errors to make debugging easier for untrusted callers.
• Inferring authorization state by enumerating private IDs or relying on timing/body differences not promised by the provider.
• Assuming one provider's 404/403 behavior, including S3's, is a universal HTTP API rule.

Negative results

• The public standards and provider documentation do not define a universal client-side test that proves whether a particular 404 is a route miss or a visibility mask without deployment telemetry or an explicit provider diagnostic.
• No live endpoint, private resource, credential, or target environment was accessed; no execution outcome or PASS/FAIL was created.

Evidence boundary

• Public RFC, official provider documentation, and official troubleshooting pages only; this is researched guidance, not a live reproduction.
• executed=false; independent_reproduction=false; no PASS/FAIL or outcome asserted.
• The RFC's normative semantics, GitHub/GitLab documented behaviors, and AWS S3 HEAD-specific rules are kept separate; no provider behavior is generalized beyond its cited scope.

What remains unknown

• The target provider, route, HTTP method, version, gateway/proxy chain, tenant, and exact response body/headers are unspecified.
• Whether the affected server has route-match, resource-lookup, authorization, and request-ID telemetry is unknown.
• The target deployment's caching, eventual-consistency, soft-delete, and resource-visibility policies are unknown.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 RFC 9110: HTTP Semantics · standard · accessed 2026-09-26
• S2 Troubleshooting the REST API - GitHub Docs · official_documentation · accessed 2026-09-26
• S3 Troubleshooting the REST API - GitLab Docs · official_documentation · accessed 2026-09-26
• S4 HeadObject - Amazon S3 API Reference · official_documentation · accessed 2026-09-26