Difference Between Status Code 401 and 402

Understanding the difference between status code 401 and 402: Core meanings and context

In the world of HTTP and API design, status codes provide a compact language for clients to understand what went wrong. The difference between status code 401 and 402 is subtle but significant: 401 Unauthorized means the request lacks valid authentication credentials, or the credentials presented are not accepted. In contrast, 402 Payment Required is a reserved code indicating that payment is required to access the requested resource. While 401 is a common, actively used signal across web apps and APIs, 402 is largely unused and often left for future standardization or vendor-specific implementations. When you design or consume an API, the distinction matters for client UX, security controls, and how the system routes users toward the next step.

From a practical perspective, treat 401 as a gate that must be crossed with valid authentication, and treat 402 as a signal that a payment or entitlement step must be completed before access is granted. This aligns with how most developers implement authentication flows and license checks in modern services. As you read this guide, keep the exact phrase “difference between status code 401 and 402” in mind—it's the foundational split between authentication failures and payment-enforced access.

In 2026, the Why Error Code team observes that teams rely heavily on 401 for login and token-refresh scenarios, while 402 remains a theoretical option that only some APIs apply. The practical takeaway is to design clear error payloads and documented flows around these codes so clients can respond deterministically.

The Core Difference: Authentication vs Payment

The distinction between 401 and 402 is all about intent. A 401 signals that the user has not proven their identity, or the server cannot verify credentials presented in the request. When a 401 is appropriate, servers typically include a WWW-Authenticate header that describes a challenge, inviting the client to re-authenticate. A 402, on the other hand, communicates that the requested action requires payment or an active entitlement. Because there is no universal payment signal standard, the exact behavior depends on the API (e.g., redirecting to a checkout, presenting a payment flow, or surfacing a clear error payload with next steps). In most real-world APIs, 401 is the default authentication failure signal, while 402 is reserved for future use or specialized paid-resource scenarios.

When to Expect a 401 Unauthorized

A 401 Unauthorized appears when credentials are missing, invalid, or considered insufficient for the requested resource. Common patterns include: invalid tokens, expired sessions, or absent Authorization headers. Clients should prompt the user to re-authenticate or refresh tokens; servers should provide a clear WWW-Authenticate header showing the required scheme. For RESTful services, a 401 often implies that the user should attempt login again, obtain a new token, or grant consent for a refreshed session. Because this signaling is well-supported across libraries, you’ll see 401 frequently in OAuth flows, API backends, and services that enforce strict identity checks.

When to Expect a 402 Payment Required

402 Payment Required remains a rarely used status code with a murkier place in modern APIs. When it appears, it signals that access depends on a payment, license, or entitlement that hasn’t been satisfied. In practice, you may see 402 accompanied by a redirect to a payment gateway, a subscription check, or a license-verification step. Since there is no universal standard, many developers opt for alternative signaling, such as 403 Forbidden with a detailed error payload explaining the payment obligation or a 402 with API-specific semantics. If you do choose to implement 402, document the flow clearly so clients know exactly what to do next.

Practical Scenarios and Examples

Consider a streaming API that offers premium content behind a paywall. A user who hasn’t subscribed or paid might receive a 402 when attempting to start playback. The API could then respond with a structured payload outlining the required action (e.g., “payment_required”: true, “amount_due”: 9.99, “currency”: “USD”) and a link to complete the payment. For an application requiring login, a 401 might be emitted if the user’s token is invalid or missing. In that case, the body should explicitly describe the failure, offer a token-refresh URL, and suggest re-authentication. These concrete examples illustrate how the two codes function in real workflows and why choosing the right one matters for UX and automation.

How Clients and APIs Should Respond

From an API design perspective, you should keep a consistent error payload structure regardless of the status code. When a 401 is returned, include a WWW-Authenticate header and a payload that helps clients recover (e.g., error_code: 401, message: 'Invalid token', retry_after: 30). For 402, if you implement it, provide explicit guidance in the response body and possibly a redirect or action URL for payment. Clients should handle 401 by redirecting users to login or refreshing tokens, and handle 402 by initiating the payment flow or displaying entitlement status. Documentation is critical to avoid ambiguity across teams and client libraries.

Security Implications and Best Practices

Security considerations for 401 include protecting against credential stuffing and excessive retry attempts. Implement rate limiting, monitor auth failures, and ensure proper token scopes. For 402, the security focus shifts to safeguarding payment data, ensuring PCI-compliant flows, and validating entitlements without exposing sensitive information. Always avoid leaking sensitive account data in error responses. Use clear, machine-readable payloads (error_code, message,

Common Pitfalls and Misconceptions

A frequent misconception is that 402 is obsolete or never used; in reality, it remains defined but underutilized. Some teams misinterpret 401 as a generic “not authorized” signal when the problem is actually an expired session; others use 403 for all permission-related cases, which obscures whether authentication or authorization failed. Another pitfall is failing to document the exact next steps for clients, leading to confused users and brittle integrations. Finally, relying on browser defaults for non-success codes without implementing consistent error payloads can degrade interoperability.

Historical Context and Industry Adoption

Historically, 401 has been the primary signal for authentication failures across the web and APIs. 402, defined in the HTTP specification, has seen limited adoption due to complexity around payment flows and licensing. Some industries—such as digital content, SaaS with tiered access, or enterprise license models—employ 402 in a controlled, server-defined way. The broader ecosystem often prefers 403 with a detailed error object or a dedicated payment-forwarding path rather than repurposing 402. As APIs evolve, teams often prefer explicit, well-documented signals over relying on a rarely used code.

Designing APIs with Clear Error Signaling

To build resilient APIs around the difference between status code 401 and 402, start with a stable error payload schema (e.g., { code: 401, message: 'Invalid token',

Key Takeaways for Developers and Teams

The difference between status code 401 and 402 is a core design decision that shapes user experience, security, and API reliability. Use 401 to indicate authentication problems and prompt re-authentication; deploy 402 only when a payment or entitlement barrier exists and you have a clear flow. Favor explicit error payloads and well-documented flows over opaque status codes. By doing so, you enable robust client implementations and smoother operator tooling.