HTTP 401 Unauthorized: Causes, Examples, and Fixes

Receiving an HTTP 401 Unauthorized status code is one of the most common encounters when integrating with web APIs, configuring authentication gateways, or building frontend client applications.

Understanding how the HTTP protocol defines status 401 allows you to quickly pinpoint whether the problem stems from missing credentials, expired tokens, or malformed request headers.

What a 401 response tells you

When a server returns a 401 response, it confirms several important technical details:

1. The server was reached: The network connection, DNS resolution, and TLS handshake succeeded.
2. The endpoint exists: The server understood the URI path and identified that it requires authentication.
3. Authentication failed or was absent: The server evaluated the request headers and found no valid identity verification.
4. The request is actionable: Sending the same request accompanied by valid credentials can result in a successful response.

GET /v1/profile HTTP/1.1
Host: api.example.test
Accept: application/json

HTTP/1.1 401 Unauthorized
Date: Thu, 10 Sep 2026 10:00:00 GMT
WWW-Authenticate: Bearer realm="example-api"
Content-Type: application/json

{"error": "unauthorized", "message": "Authentication credentials were not provided."}

GET /v1/reports HTTP/1.1
Host: api.example.test
Authorization: Bearer example_expired_token
Accept: application/json

HTTP/1.1 401 Unauthorized
Date: Thu, 10 Sep 2026 10:00:00 GMT
WWW-Authenticate: Bearer realm="example-api", error="invalid_token", error_description="The token has expired"
Content-Type: application/json

{"error": "invalid_token", "message": "The access token provided has expired."}

Common causes of HTTP 401

Missing or malformed credentials

The HTTP request omitted an Authorization header or required session cookie entirely when attempting to access a protected endpoint.

Expired, revoked, or otherwise invalid credentials

The client supplied an authentication token, but the token lifetime has elapsed, or the server revoked the token session.

Authentication scheme mismatch

The client sent credentials with an unrecognized scheme prefix, improper encoding, or formatted the header contrary to the server specification.

Wrong environment, issuer, audience, or credential context

The cryptographic signature or token claims failed validation against the server secret key or public key.

The WWW-Authenticate header

For a standards-conformant 401 response, RFC 9110 specifies that the origin server ought to send a WWW-Authenticate header field containing at least one challenge applicable to the requested resource.

The header indicates the authentication scheme expected by the server:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example-api", error="invalid_token", error_description="The token has expired"

Common authentication schemes specified in WWW-Authenticate include:

• Bearer: Used for token-based authentication (such as JWTs or OAuth 2.0 access tokens).
• Basic: Used for base64-encoded username and password pairs.
• Digest: A challenge-response mechanism using MD5 or SHA hashing.

Reading the WWW-Authenticate header provides direct diagnostic clues about why the server rejected the request.

How to investigate a 401 safely

When debugging an unexpected 401 error, follow a structured diagnostic workflow:

1. Inspect outgoing request headers: Verify whether your HTTP client is transmitting the Authorization header with the expected prefix (e.g., Bearer).
2. Examine the response payload: Many APIs return JSON error descriptions detailing whether a token is expired, malformed, or unrecognized.
3. Validate token expiration: Decode the token timestamp to verify that the current system time falls within its valid window.
4. Never log sensitive credentials: When printing debug traces or curl commands, always redact production secrets and active access tokens.

HTTP 401 vs. HTTP 403

Although both status codes indicate an access barrier, they address different concerns:

• HTTP 401 Unauthorized: Addresses authentication (“Who are you?”). The client is unauthenticated, or credentials were invalid.
• HTTP 403 Forbidden: Addresses authorization (“What are you allowed to do?”). The server knows the client’s identity, but refuses to grant access due to permissions or policy.

If re-authenticating with valid credentials can solve the issue, the appropriate code is 401. If no change in credentials will grant access because the account lacks permission, the appropriate code is 403.

HTTP 401 and CORS are different issues

Developers sometimes confuse 401 errors with CORS errors when working with browser-based Single Page Applications (SPAs).

HTTP 401 is returned directly by the API server when credentials fail. However, if a browser makes a cross-origin request that encounters a 401 response, the browser will block JavaScript from reading the response payload unless the server also returns valid CORS response headers such as Access-Control-Allow-Origin.

Inspect browser DevTools Network panel observations to distinguish between a CORS preflight failure and an origin server 401 response lacking CORS headers.

What to check before changing code

Before altering client application code or token exchange logic, verify the following checklist:

How to verify the fix

Send a request with a sanitized test header using curl to inspect authentication challenge behavior:

curl -i https://api.example.test/v1/profile \
  -H "Authorization: Bearer example_token_abc"

Review the WWW-Authenticate response header and status code to confirm whether the server accepts the credential scheme and format.

Key takeaway

HTTP 401 Unauthorized means authentication credentials are required and were either missing, invalid, or expired. Check the WWW-Authenticate response header, confirm that your client sends the expected Authorization header, and verify token validity before modifying application authorization logic.