What the 402 status code means

The HTTP 402 Payment Required status code is a reserved response indicating that payment is necessary to access the requested content. Unlike 401 (Unauthorized) or 403 (Forbidden), which handle authentication and permission issues, 402 specifically signals a financial barrier. It was originally defined in RFC 7231 as a placeholder for future payment systems, yet it remained largely unused for decades.

For thirty years, developers bypassed this code, relying instead on subscription gateways or ad-supported models. The 402 error code effectively sat dormant, a ghost in the HTTP specification. However, the rise of x402 has brought it back into focus. This new framework treats the 402 status not as an error, but as a standard mechanism for machine-to-machine micropayments. It allows servers to request payment directly in the HTTP handshake, enabling a shift toward direct content monetization without intermediaries.

Understanding this distinction is critical. When you encounter a 402 Payment Required response, it is not a technical glitch. It is a deliberate instruction from the server: the resource is available, but the transaction must be completed first. This marks a fundamental change in how web services handle access control, moving from identity-based checks to value-based exchanges.

Steps to resolve a 402 error

A 402 Payment Required error means the server is explicitly blocking access because a payment is mandatory. Unlike a 403 Forbidden error, which signals an authorization issue, a 402 response indicates that the resource is behind a paywall or requires a transaction to proceed. To fix a 402 Payment Required error, you must address the payment status on the client side or verify the configuration on the server side.

1
Verify payment method and billing details

For end-users, the most common cause of a 402 error is an expired credit card or insufficient funds. Log in to your account dashboard and navigate to the billing or subscription settings. Ensure that your payment method is active, the expiration date is current, and the billing address matches the one on file with your bank. If the payment fails, the server will continue to return a 402 response until the transaction is completed.

2
Check API keys and access tokens

If you are a developer integrating with a paid API, a 402 response often indicates that your subscription tier has been exceeded or your account is past due. Verify that your API key is valid and has not been revoked due to non-payment. Check your provider’s dashboard for any outstanding invoices or service suspensions. Updating your payment information on the provider’s portal usually resolves the issue immediately.

3
Process payment via the gateway

If the error persists after verifying your details, you may need to manually trigger a payment retry. Some systems require you to click a "Retry Payment" button in the user interface to process the transaction. For API users, this might involve re-authenticating or sending a new request after the payment gateway confirms the funds have been captured. Ensure that your webhook endpoints are configured to handle payment success events so your application can update its access permissions accordingly.

4
Retry the original request

Once the payment has been processed and confirmed, clear your browser cache or restart your application to ensure you are not using stale session data. Retry the original request that triggered the 402 error. If the payment was successful, the server should now grant access and return a 200 OK status code. If the error continues, contact the service provider’s support team with your transaction ID for further investigation.

Configuring x402 for agentic commerce

The revival of the HTTP 402 Payment Required status code is driven by the Machine Payment Protocol (MPP). This standard allows software agents to negotiate, pay, and access resources without human intervention. Implementing x402 requires configuring both the client to send proof of payment and the server to validate it.

1. Set the x402 Header

When a server requires payment, it returns a 402 status. The client must include the x402 header in subsequent requests to prove that the required payment has been settled. This header contains a cryptographic proof or transaction ID that links the request to a completed payment event.

2. Validate MPP Compliance

The server must verify the x402 proof against the MPP standard. This involves checking the signature, the payment amount, and the expiration of the proof. If the proof is valid, the server grants access to the resource. If invalid or missing, the server returns a 402 error again, forcing the agent to initiate a new payment flow.

3. Handle Payment Failures

Agents must be programmed to handle payment failures gracefully. If the x402 proof is rejected, the agent should trigger a new payment transaction. This loop continues until the payment is confirmed and the proof is updated. Ensure your error handling logic prevents infinite loops by setting a maximum retry limit.

HTTP
GET /api/resource HTTP/1.1
Host: api.example.com
x402: proof=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...&amount=0.01&currency=USD

This header example shows a valid x402 proof. The proof field contains a JWT signed by the payment provider. The amount and currency fields confirm the transaction details. Servers must parse these fields to validate the payment against the MPP standard.

Common mistakes when handling 402 payment required errors

The 402 Payment Required status code is rare in modern web development, which often leads to confusion. Developers and site owners frequently misdiagnose the error, applying fixes for authentication or permission issues to a problem that is strictly financial. This section outlines the most frequent pitfalls and how to avoid them.

Confusing 402 with 403 Forbidden

The most common error is assuming a 402 response means the user is not logged in or lacks permissions. A 403 Forbidden error indicates access is denied due to security policies or missing authentication tokens. In contrast, a 402 Payment Required error explicitly states that access is granted only after payment is received. If your server returns 402, do not redirect users to a login page. Check your payment gateway integration and billing logic instead.

Ignoring Non-Refundable Policies

When a 402 error occurs, it often blocks access to premium content or services. If a user has already paid but still sees the error, it may be a caching issue or a sync failure between your payment processor and your application. However, if the payment failed, ensure your error messages clearly explain why. Do not obscure non-refundable policies in fine print. Clear communication reduces support tickets and builds trust with users who are trying to complete a transaction.

Failing to Validate Payment Proofs

Another frequent mistake is relying solely on client-side confirmation that a payment went through. Always validate the payment proof on the server side. Webhooks from payment processors like Stripe or PayPal can fail or be delayed. If your application grants access based only on a successful JavaScript callback, you risk revenue loss and security vulnerabilities. Implement server-side verification to ensure the 402 error is only cleared when the payment is definitively confirmed.

Verify your payment integration works

After updating billing details or generating payment proof, you need to confirm the 402 payment required error is gone. A successful integration test ensures the server accepts the transaction and releases the restricted content.

Follow this checklist to validate the fix:

  • Payment method updated: Confirm the new card or crypto wallet is saved and active in your account settings.
  • API keys valid: Check that your secret keys have not expired or been rotated incorrectly during the update.
  • Payment proof generated: Ensure the transaction ID or receipt is visible in your dashboard history.
  • Request retried successfully: Reload the protected page or re-run the API call to verify access is granted.

If the error persists, clear your browser cache and cookies. Stale session data often holds onto the previous denied state. If you still see the 402 status, contact your payment provider to verify the funds cleared on their end.