Join our Newsletter — 33% off our NHI Course
Home› FAQ› Authentication, Authorisation & Trust› How should teams decide between 401 and 403…
Authentication, Authorisation & Trust

How should teams decide between 401 and 403 in API error handling?

← Back to all FAQ
By NHI Mgmt Group Editorial Team Updated October 31, 2026 Domain: Authentication, Authorisation & Trust

Use 401 when the client has not authenticated successfully, or the credentials are missing, invalid, expired, or need stronger authentication. Use 403 when the server knows the caller’s identity but will not allow the requested action. The practical test is simple: 401 says provide or refresh credentials, while 403 says credentials alone will not grant access.

How to choose the right status code for authentication failures versus authorization failures

The cleanest way to decide is to ask whether the server can establish the caller’s identity. If it cannot, return 401 and make the client authenticate again. If it can, but the caller still lacks permission for the action, return 403. That distinction keeps API clients, gateways, and audit trails aligned on whether the next step is re-authentication or access denial.

A useful implementation habit is to separate identity checks from entitlement checks in the request flow. Authentication outcomes should be decided before business authorization rules run, so the response can be consistent and the error path does not leak extra detail. This is especially important when a global handler formats API errors, because the response shape should stay stable even when the underlying failure comes from a different layer.

In practice, 401 is about the credential state, not the user’s intent. Missing credentials, malformed credentials, expired sessions or tokens, and cases where stronger authentication is required all belong here. A 403 response means the server recognises who is calling, but the action is outside the caller’s allowed scope, role, policy, or resource boundary.

What API teams should avoid when mapping errors to 401 and 403

The most common mistake is using 403 for every denial because it feels safer or simpler. That weakens client behaviour, because the caller cannot tell whether it should retry with fresh credentials, prompt the user, or stop entirely. The opposite mistake is returning 401 after authentication has already succeeded, which encourages pointless retries and can hide a genuine privilege issue.

Another failure mode is making the status code depend on implementation convenience rather than semantics. For example, if a handler sees an invalid token but the surrounding code is really enforcing a business rule, the response should still reflect the earliest meaningful decision. The error code should describe the control boundary that failed, not the deepest stack frame that noticed it.

Well-designed APIs also keep the message body from contradicting the status code. If the server returns 401, the response should indicate that valid credentials are needed or need refreshing. If it returns 403, the body should avoid suggesting that a new login will fix the problem. That consistency matters for automated clients, developer tooling, and troubleshooting.

When the caller is authenticated but access is denied for a resource-specific reason, keep the denial precise. That can mean the user is authenticated but not in the right role, the token lacks the needed scope, or the request is outside an ownership boundary. The status code stays 403, even if the root cause is a business policy rather than a classic role check.

How to make 401 and 403 decisions consistently in an API

The simplest decision rule is to evaluate the request in this order: first, can the server trust the caller’s identity; second, does that identity have the required permission. If the first answer is no, use 401. If the first answer is yes and the second is no, use 403. That sequence gives teams a predictable rule that survives framework changes and reduces debate during incident review.

Consistency improves when teams define one error contract for the whole API surface. Shared middleware, consistent token validation, and a common authorisation layer prevent one endpoint from returning 401 for an access rule while another returns 403 for the same condition. The API should behave the same way whether the request comes through a gateway, a service mesh, or directly to the application.

Documentation should also tell clients what to do next. A 401 response may need a challenge, a refreshed token, or a stronger authentication step. A 403 response should tell the caller that the request is not allowed even with valid credentials, which helps client developers avoid building retry loops that cannot succeed.

If you want a broader API design view of this pattern, the Secure API Design Guide covers safe errors alongside object and field authorisation. The same design principle is reinforced by OWASP API Security Top 10, which frames broken authorisation as a core API risk.

Risk and Threat Considerations

Incorrectly choosing between 401 and 403 is not just a style issue. It can expose auth workflow weaknesses, confuse clients into repeated retry attempts, and make it harder to detect when a denial is caused by expired credentials versus a true privilege boundary. In security-sensitive APIs, that distinction affects both user experience and how quickly teams can spot abnormal access patterns.

Failure mechanism: If authentication and authorization are blended together, an API may return the wrong code, leak too much about the request path, or allow a client to keep retrying when the right action is actually re-authentication or access review.

Impact: The result is inconsistent client behaviour, weaker auditability, and more room for attackers to probe which credentials are valid, which endpoints enforce policy, and where the access boundary is implemented.

Standards & Framework Alignment

This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.

OWASP API Security Top 10 addresses the attack and risk surface, while OWASP ASVS, NIST SP 800-53 Rev 5 and NIST CSF 2.0 set the governance and control requirements practitioners need to meet.

FrameworkControl / ReferenceRelevance
OWASP ASVSV6 — Authentication401 handling depends on whether authentication succeeded.
V8 — Authorization403 reflects authenticated callers denied by access rules.
Recommendation — Enforce clear authentication outcomes before permission checks and map failures to 401. Return 403 when a validated identity lacks the required privilege.
NIST SP 800-53 Rev 5IA-2 — Identification and Authentication (Organizational Users)API callers must be authenticated before authorization can be enforced.
AC-3 — Access Enforcement403 is the access-enforcement outcome for authenticated callers without permission.
Recommendation — Validate caller identity first, then enforce access decisions. Apply access enforcement consistently and deny unauthorized actions with 403.
OWASP API Security Top 10API5 — Broken Function Level Authorization403 decisions commonly arise from function-level authorization failures.
Recommendation — Check function-level permissions and deny disallowed actions explicitly.
NIST CSF 2.0PR.AA-05 — Authentication Confirms Identities and CredentialsThe 401/403 split hinges on whether identity is confirmed.
Recommendation — Confirm identity before evaluating whether the request is permitted.

Practitioner Guidance

What to verify: Confirm that every protected endpoint has a clear separation between identity validation and permission evaluation, and that the response code follows the earliest failed step. Test expired credentials, missing credentials, valid credentials with insufficient rights, and valid credentials with the wrong scope.

Common mistake: Do not let framework defaults decide the code for you without review. Many teams accidentally standardise on one status for all denials, then discover later that client retry logic, support tooling, and security logs all interpret the failure differently.

Practitioner takeaway: Use 401 to tell the client “authenticate again,” and 403 to tell it “authentication is not the issue, access is.” If that distinction is unclear in your API, the error contract is too weak.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Reviewed and updated by the NHIMG editorial team on October 31, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org