What HTTP 402 Means for APIs

The HTTP 402 status code is no longer just a placeholder in the specification. While MDN Web Docs describes it as "reserved for future use," the industry has quietly adopted it as the standard for Pay-Per-API transactions. It sits in the 400-class error range, signaling that the server requires payment before fulfilling the request.

This distinction is critical for agentic workflows. When an AI agent encounters a 401 Unauthorized, it knows it lacks authentication credentials. A 403 Forbidden indicates it lacks permission. A 402 Payment Required tells the agent that the resource exists and it is authorized, but the transaction hasn't cleared yet. This clarity allows automated systems to trigger a micropayment flow—such as a Bitcoin Lightning invoice—without human intervention.

For developers, this transforms API gateways from simple access controls into financial endpoints. Instead of relying on subscription models or complex billing cycles, you can return a 402 with a payment request header, allowing the client to settle the debt and retry the request immediately.

Set up the payment gateway

To implement HTTP 402 micropayments, you need a provider that understands the 402 status code and can process cryptocurrency transactions automatically. Standard gateways like Stripe or PayPal do not support this natively, so you must choose a Web3-native solution. Popular options include Nansen’s x402 protocol, Abstract API, or custom smart contract integrations.

The goal is to configure your API so that it returns a 402 Payment Required response when a user has not paid, and then automatically grants access once the transaction is confirmed on-chain.

1
Choose a payment provider

Select a provider that supports the HTTP 402 standard. For this guide, we use Nansen’s x402 as the primary example, but the logic applies to Abstract API or other compatible gateways. Ensure the provider supports the specific blockchain network you plan to use (e.g., Ethereum, Polygon, or Solana). Visit the Nansen x402 documentation to review supported networks and pricing models.

2
Generate API credentials

Create an account with your chosen provider and generate your API keys. Most providers require you to link a wallet address for receiving payments. Store your private keys or API secrets securely; never expose them in client-side code or public repositories. You will need these credentials to authenticate your server’s requests to the payment gateway.

3
Configure endpoint pricing

Define the cost for each API endpoint. Pricing can be fixed per request, tiered based on data volume, or dynamic based on network gas fees. For example, you might set a simple endpoint like /api/weather to cost 0.001 ETH, while a heavy data endpoint like /api/analytics costs 0.01 ETH. Configure these prices in your provider’s dashboard or via their SDK.

4
Implement the 402 response logic

Update your server-side code to check for payment status before returning data. If a request is made without valid payment proof, return an HTTP 402 Payment Required status code. Include a Paywall header or a JSON body with payment instructions, such as the amount due, the recipient wallet address, and the required blockchain network. This allows the client to initiate a transaction.

5
Handle payment verification

Once the client sends a transaction, your server must verify it on-chain. Use the provider’s webhook or polling mechanism to confirm that the payment has been received and the transaction is confirmed. Once verified, grant the user access to the endpoint for the duration of their subscription or per-request validity period. Log the transaction hash for auditing purposes.

Configure priced endpoints

Defining which API routes trigger a 402 response requires mapping your payment logic to specific URL patterns. This setup ensures that only the resources you intend to monetize are behind the paywall, while public or free endpoints remain accessible.

Define your payment gateway routes

Start by identifying the specific API paths that require payment. These are typically your premium data endpoints, high-value computations, or rate-limited resources. In your middleware or routing configuration, tag these routes as "paid." When a request hits one of these paths without a valid payment token or transaction hash, the system should immediately return an HTTP 402 status code instead of processing the request.

Set up the 402 response handler

The 402 status code is the signal that payment is required. Configure your server to return this code with a body that explains the next steps. This body should include a link to your payment gateway or a specific transaction ID that the client must resolve. For example, a response might look like this:

JSON
{
  "error": "Payment Required",
  "code": 402,
  "message": "Please complete the transaction for this resource.",
  "payment_url": "https://your-api.com/pay/endpoint-id"
}

This approach keeps the API clean and predictable. Clients can programmatically detect the 402 status and trigger their own payment flows without guessing why a request failed.

Test with mock transactions

Before going live, test your priced endpoints using mock transactions. Verify that the 402 response is returned when no payment is detected, and that the endpoint processes correctly once a valid payment is confirmed. This step is critical to ensure that your payment logic doesn't accidentally block legitimate free traffic or fail to charge for paid usage.

Handle payment failures

A 402 Payment Required error is the API’s way of saying the wallet signature didn’t match the expected payment state. Unlike a 401 (unauthorized) or 403 (forbidden), this error is specific to billing logic. When your Web3 integration triggers this response, it usually means the smart contract or payment gateway rejected the transaction due to missing funds, expired credentials, or a mismatched signature.

Treat these errors as debugging opportunities rather than system crashes. Follow this sequence to isolate the failure point.

Verify credentials and subscriptions

Start by confirming that your application is correctly registered with the API provider. Many 402 errors stem from an application that is active but not subscribed to the specific paid tier required for the endpoint you are calling. If you are using a platform like Azure or AWS, double-check your subscription status and ensure your API keys have the necessary permissions.

Check wallet signatures and balances

For Web3-native APIs, the 402 error often indicates that the wallet signature is invalid or the connected wallet lacks sufficient native tokens to cover the gas fees or the API fee itself. Verify that the wallet address signing the request matches the one on file. If you are testing locally, ensure your testnet wallet has the required test tokens. A mismatched signature will be rejected before the payment is even processed.

Review quota and rate limits

Some APIs return a 402 when a user exceeds their monthly quota or rate limit for a paid plan, effectively treating overage as a payment requirement. Check your usage dashboard to see if you have hit a hard limit. If so, you may need to upgrade your plan or wait for the billing cycle to reset.

Verify transaction success

Once the client submits the payment, you need to confirm two things: the blockchain transaction is settled, and your backend has unlocked the requested resource. In a pay-per-API flow, skipping this verification step is like handing over the keys before the buyer pays.

Start by checking the transaction status on the blockchain. Don't rely on the client's promise that they "sent it." Use a block explorer or an indexer to verify the txHash included in the request. For high-stakes transactions, wait for a few confirmations to ensure the payment is irreversible. If the transaction fails or is reverted, the API should return a 402 Payment Required error again, prompting the user to retry.

Next, validate the access grant. Your backend should update the user's session or issue a short-lived JWT (JSON Web Token) only after the payment is confirmed. This token becomes the key for subsequent API calls. If you're using a standard HTTP 402 response, ensure the Retry-After header is set correctly so the client knows when to check back. For real-time updates, consider using webhooks to notify your server the moment the payment lands, reducing the latency between payment and access.

If the payment is confirmed but access isn't granted, check your internal ledger. Sometimes, the blockchain is fine, but your database hasn't synced the new balance. Logging the txHash against the user ID helps debug these mismatches without exposing sensitive wallet addresses to the client.