← Blog

HTTP Status 401 vs. 403 for LLM APIs

Parminder Singh
Parminder Singh··7 min read
Summarize with AI

HTTP 401 and 403 represent different failure states for an LLM API. A 401 says the target resource lacks valid authentication credentials and requires a WWW-Authenticate challenge. A 403 says the server understood the request and refuses it, often because a valid principal lacks model or route authority. Tenant and scope rules can produce the same refusal, as can data-policy rules. This guide defines the contract, disclosure limits, retry behavior, and release tests.

Platform & Architectureai-securityllm-securityidentity-and-authorizationzero-trustpolicy-enforcementaudit
HTTP Status 401 vs. 403 for LLM APIs

A 401 response means an LLM API request lacks valid authentication credentials for its target resource. A 403 means the server understood the request and refuses to fulfill it. That one-bit distinction changes credential refresh and retry behavior. It also changes client messaging and incident telemetry, along with the policy evidence kept for an authenticated model call.

I test both states side by side. The left terminal uses an expired token and receives 401 with WWW-Authenticate. The right uses a valid analyst token against a restricted model and receives 403. Every intermediary should preserve that split.

TL;DR

  • Return 401 when the LLM resource lacks valid authentication credentials, and include at least one applicable WWW-Authenticate challenge.
  • Return 403 after the server understands the request and refuses it, including valid identities denied by model or route rules. Scope and tenant denials also qualify, as do data-policy denials.
  • For Bearer tokens, map invalid or expired tokens to 401 and insufficient scope to 403 under RFC 6750.
  • Give clients stable machine reasons, limit sensitive disclosure, and test credential refresh separately from authorization denial.

401 starts a credential replacement path

RFC 9110 Section 15.5.2 defines 401 Unauthorized for a request that has not been applied because valid authentication credentials are missing for the target resource. The historical status name is awkward. Its mechanism is still clear: authentication failed or never arrived.

The server must send a WWW-Authenticate field with at least one challenge applicable to the resource. Section 11.6.1 permits more than one challenge and warns that each challenge can contain a comma-separated parameter list. A proxy forwarding the response must preserve the field.

An LLM API should document its challenge per route. A Bearer challenge can identify the scheme and approved error parameters for the relevant protection space. A workload endpoint using mutual TLS might expose a different client-facing authentication contract. The challenge describes the resource the caller reached, rather than every private provider credential used behind the gateway.

Clients may repeat a 401 request with a new or replaced Authorization field. That behavior makes 401 operationally expensive when used carelessly. An SDK can start token refresh, invoke an identity provider, and repeat a large prompt. Use it only for a state that replacement credentials can plausibly repair.

403 records a refusal after request understanding

RFC 9110 Section 15.5.4 defines 403 Forbidden for a request the server understood and refuses to fulfill. Credentials can be valid yet insufficient. The reason can also sit outside credential scope.

At an LLM boundary, 403 can cover a valid employee denied a restricted model, an agent whose delegation excludes a route, a tenant blocked from a provider account, or a prompt whose data classification conflicts with the approved destination. Authentication has already identified the principal. Request-time policy makes the second decision.

The client should stop automatic repetition with the same credentials. New credentials may change the result, although many 403 decisions depend on the route or model. Data class and region can also control the result, as can delegated authority. A corrected request can also succeed when the caller changes an unauthorized parameter under a documented contract.

The post-authentication gap guide covers the architecture behind this status. A valid identity supplies one policy input. It never grants blanket authority over every model request.

My blunt view is that returning 401 for every denial is lazy API design. It trains clients to hammer the identity system when the policy engine has already made a stable refusal.

Bearer token errors sharpen the split

RFC 6750 Section 3.1 defines Bearer token error values for protected resources. An expired, revoked, malformed, or otherwise invalid access token maps to invalid_token, with 401 as the recommended status. A request requiring privileges beyond the token maps to insufficient_scope, with 403 as the recommended status.

A missing token deserves restrained disclosure. RFC 6750 says a resource server should omit the error code when the request lacks authentication information. The Bearer challenge can still identify the scheme and realm. That response tells a legitimate client how to authenticate while avoiding needless detail for an unauthenticated probe.

For an LLM API, separate verifier reasons before authorization runs. Parse failures and invalid signatures need distinct protected codes. Record unacceptable issuers and wrong audiences separately, then distinguish an unsupported scheme from expiry or revocation. These failures can share a public invalid_token response. Raw tokens stay out of logs.

After successful verification, evaluate scopes and richer policy inputs. A scope might allow model.invoke, while route policy restricts the caller to one model family and a low-sensitivity data class. A valid scope can still end in 403 under that policy. The per-request LLM authorization guide describes the request context that follows token validation.

Disclosure policy controls the response body

RFC 9110 permits a server to explain a 403 in the response content. It also permits an origin server to use 404 when it wants to hide the current existence of a forbidden resource. Choose that behavior per resource class and apply it consistently.

A public model catalog can return a stable 403 problem type such as model_not_allowed. A sensitive tenant route may use 404 externally while recording the actual authorization denial internally. Avoid returning provider account IDs, group memberships, internal policy expressions, token claims, or alternate restricted model names.

Machine-readable errors should carry a stable type, a safe title, an occurrence identifier, and an approved reason code. Keep the HTTP status aligned with the body's status value. Human prose can change without breaking the client, while the typed reason supports remediation.

The occurrence identifier should join the response to a protected decision event. The AI audit log chain-of-custody guide explains how that event stays useful after it leaves the request path. Protect any endpoint that dereferences the identifier.

Gateway roles need separate authentication contracts

An application and policy gateway can each authenticate a different principal, as can an LLM provider. The application authenticates the human session. The gateway might verify a workload token carrying trusted user context. The provider authenticates the gateway through a separate API credential or workload identity.

Map each HTTP hop with its issuer and audience. Record its verifier and challenge owner. Identify its policy decision point. A 401 generated by the gateway should describe the client-facing gateway resource. Passing a private provider challenge through unchanged can disclose the wrong protection space and prompt the client to present credentials to the wrong protection space.

If the gateway merely forwards an upstream response, RFC 9110 requires preservation of WWW-Authenticate. If it terminates one security contract and originates a new provider request, it needs an explicit translation policy. Record the upstream status privately and return the documented client-facing status. Avoid collapsing every upstream 401 or 403 into a generic 500.

Proxy authentication has its own 407 status and Proxy-Authenticate field. Keep it separate from origin authentication. An enterprise forward proxy requesting credentials is a different party than an LLM API challenging its caller.

The release fixture proves client behavior

Run negative tests through the deployed identity provider and load balancer. Continue through the gateway and provider adapter, then the client SDK. Assert both the response and the next client action.

  • Missing credentials receive 401 and a valid challenge with limited detail.
  • An expired or revoked Bearer token receives 401 with the approved invalid_token contract.
  • Wrong issuer, wrong audience, malformed signature, and unsupported scheme fail before route authorization.
  • A valid principal lacking scope receives 403. The same applies to model, tenant, region, or data-class denial under route policy.
  • Repetition with the same credentials stops after 403.
  • One bounded refresh can follow 401. A second identical challenge ends the loop.
  • Multiple challenges survive intermediary parsing, and proxy 407 behavior remains separate.
  • A hidden resource returns the selected external status while protected telemetry retains the actual policy result.

Capture the challenge, public error type, verifier reason, resolved principal, route, model, policy version, decision, and client retry count. Redact credentials and sensitive prompt content. A release fails when 403 starts a refresh loop or when a 401 reaches the client without a usable challenge.

DeepInspect

DeepInspect can evaluate authenticated user or agent requests deliberately routed through its HTTP path to an LLM endpoint. It uses trusted identity context with route, model, tenant, data classification, and policy. A valid principal can therefore receive an identity-aware deny decision after authentication succeeds, with a per-decision record tied to the routed request.

The identity provider still owns authentication, token issuance, revocation, and reauthentication. The application owns its user-facing session and the client behavior triggered by 401 or 403. Provider credentials retain separate custody. Direct provider calls and local runtimes remain outside its enforcement evidence, along with HTTP traffic that bypasses DeepInspect.

Book a demo today.