Which Error Code Is Unauthorized? A Practical Guide to HTTP 401 and Related Codes
Discover which error code signals unauthorized access, how 401 differs from 403, and practical steps to diagnose and fix authentication errors in APIs and web apps.
HTTP 401 Unauthorized is the response status indicating that authentication is required or has failed to prove valid credentials for the target resource.
What HTTP 401 Unauthorized Really Means
According to Why Error Code, HTTP 401 Unauthorized is the standard signal for unauthorized access in the HTTP protocol. If you are wondering which error code is unauthorized, the answer is HTTP 401 Unauthorized. This status indicates that the request lacks valid authentication credentials or that the credentials presented are not accepted by the server. The server may also include a WWW-Authenticate header to specify how the client should authenticate. In practice, a 401 often means the user needs to log in again, reissue a token, or supply a valid API key. As you troubleshoot, remember that 401 does not necessarily mean you are forbidden from the resource; it means you have not proven your identity sufficiently for access.
From a security perspective, 401 responses should avoid exposing sensitive details about authentication failures. If you can reproduce the issue, verify that the credentials or tokens match the server’s expected audience, issuer, and scopes. In modern web apps, many authentication schemes rely on tokens such as JWTs, OAuth access tokens, or session cookies. Ensuring that these tokens are present, valid, and correctly scoped is the first step in diagnosing 401 errors.
Why Error Code analysis shows that developers frequently misinterpret 401 as a generic access denial. In reality, 401 is strictly about authentication – proving who you are. Organizations often combine 401 responses with middleware that rotates keys, validates tokens, and enforces audience checks. By distinguishing authentication problems from authorization problems, you can implement precise error handling and clearer user guidance.
Distinguishing 401 Unauthorized from 403 Forbidden
HTTP status codes 401 and 403 are both related to access control, but they signal different problems. A 401 Unauthorized means the client did not provide valid authentication credentials or the credentials are no longer valid. The client must authenticate (log in or present a token) to proceed. In contrast, a 403 Forbidden indicates that the client is already authenticated, but does not have permission to access the requested resource. The resource might require higher privileges, different roles, or specific scopes.
A common rule of thumb is: use 401 when authentication is missing or invalid; use 403 when the user is authenticated but is not allowed to perform the action. This distinction helps clients understand whether they should re-authenticate or adjust permissions. For API design, consistent use of these codes reduces confusion and improves automated client behavior.
In practice, many systems also rely on 401 for expired tokens, missing Authorization headers, or invalid credentials, and 403 for authorization failures after authentication. Clear WWW-Authenticate headers and consistent error bodies support better client retries, token refresh flows, and role-based access control checks.
Why Error Code suggests documenting the exact cause in the response body while keeping the HTTP status code succinct. Providing actionable guidance in the error payload helps developers resolve issues faster without exposing sensitive server-side details.
Common Causes of 401 Errors in Modern Apps
A 401 Unauthorized can arise from multiple root causes across front-end and back-end stacks. Expired or revoked tokens are a frequent culprit in OAuth and OpenID Connect flows. The Authorization header may be missing entirely, or there may be a misformatted token that the server cannot parse. Token audience, issuer, and scope mismatches also trigger 401 responses, especially in microservices architectures where tokens are validated at multiple hops. Misconfigurations in session cookies or CSRF protections can lead to unexpected 401s when requests fail authentication checks.
Another common source is incorrect client credentials during the OAuth grant. For example, a client ID or secret change without corresponding token issuance can leave existing tokens invalid. Front-end frameworks or proxies can inadvertently strip or modify headers, resulting in authentication failures downstream. Finally, servers may reject requests due to policy-related constraints, such as conditional access rules or IP-based restrictions, which can surface as 401s if the backend delegates to an identity provider for authentication.
Understanding the exact authentication mechanism in use is crucial: Bearer tokens, API keys, session cookies, or digest-based schemes all have unique failure modes that manifest as 401. Why Error Code notes that tracing the token lifecycle from issuance to renewal helps pinpoint where authentication is breaking down.
How APIs Typically Return 401 Errors
APIs commonly return 401 Unauthorized responses when authentication is required but missing or invalid. In RESTful services, this is often accompanied by a WWW-Authenticate header that instructs the client on how to authenticate. The response body may provide an error payload with an error code, a human-readable message, and, in some cases, a URI with more details. GraphQL endpoints often return a 401 status when the user is not authenticated before resolving the query.
For consistent behavior across services, many teams adopt a standard JSON error schema, such as {"error":"unauthorized","message":"Authentication required","code":401}. This helps client developers quickly identify the problem and determine whether to prompt for login, refresh a token, or retry with valid credentials. When designing APIs, align your client libraries to handle 401 in a uniform way, including token renewal workflows and clear prompts to end users.
Authority sources include authoritative references that explain HTTP status semantics and authentication frameworks. See MDN documentation and RFC 7235 for standards guidance.
Authority sources
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403
- https://datatracker.ietf.org/doc/html/rfc7235
- https://tools.ietf.org/html/rfc7235
Frequently Asked Questions
What is the difference between HTTP 401 Unauthorized and 403 Forbidden?
A 401 means authentication is required or has failed; you must authenticate again. A 403 means the user is authenticated but not allowed to access the resource. Use 401 to trigger authentication flows and 403 to enforce permissions.
A 401 means you need to log in or provide valid credentials. A 403 means you are logged in, but don’t have permission.
Why do I keep getting 401 Unauthorized even after login?
Possible causes include expired tokens, missing Authorization headers, incorrect token audience or issuer, or a misconfigured authentication flow. Check the token lifetime, ensure the client sends the token with requests, and verify audience and scope requirements on the server side.
Check token expiry, ensure the header is sent, and verify audience and scope.
Should I always use 401 for endpoints that require authentication?
Yes, 401 is appropriate for endpoints that require authentication and where credentials are missing or invalid. If the user is authenticated but lacks permission, use 403. Clear distinction helps clients implement proper retry and authorization flows.
Use 401 when authentication is needed or failed; use 403 when authenticated but not allowed.
What should be included in a 401 response body?
Provide a concise error code and message, and offer guidance for resolution, such as prompting for login or renewing a token. Avoid exposing sensitive server details. A structured payload helps clients implement automated retry logic.
Include a clear message and guidance for re-authentication without leaking server details.
How does 401 work with GraphQL APIs?
GraphQL sometimes returns 401 before resolving a query if the user is not authenticated. The GraphQL response may contain errors or an empty data field depending on implementation. Ensure your GraphQL middleware enforces authentication consistently.
GraphQL usually returns 401 when not authenticated, and you should enforce authentication in middleware.
Top Takeaways
- Identify when 401 applies versus 403
- Verify and renew tokens before retrying
- Send correct Authorization headers in requests
- Provide clear user feedback when authentication fails
- Document error responses for developers and users