HTTP Status Code Decision Matrix

Interactive RFC 9110 decision engine and dilemma resolver for REST API status codes (401 vs 403, 301 vs 308, 400 vs 422)

Architectural Dilemma Resolver

Clarify common ambiguous API design decisions

RFC 9110 & 9111

A user attempts to access an endpoint protected by security policies.

RFC Recommended Best Practice

Recommendation: Use 401 if we do not know who the user is (unauthenticated). Use 403 if we know who they are, but they lack permission.

Inspect Details:vs

401

RFC 9110, Section 15.5.2

4xx

Authentication is required and has failed or has not been provided.

When to use

Missing, expired, or invalid API key or Bearer token.

When NOT to use

When the user IS authenticated, but lacks sufficient permissions (use 403).

Recommended Response Headers:

WWW-Authenticate: Bearer error="invalid_token"

Standard Problem/Success Payload:

{
  "error": "Unauthorized",
  "message": "Bearer token expired or missing."
}