What is HTTP 402 for APIs

HTTP 402 Payment Required is an HTTP status code defined in RFC 7231 (Section 6.5.12) that indicates the server requires payment to fulfill the request. While historically reserved for digital payment systems, modern API architectures use it to enforce pay-per-use models, metered billing, or subscription gates before returning data.

Unlike 401 (Unauthorized) or 403 (Forbidden), which relate to identity and permissions, 402 specifically signals a financial barrier. For developers, this means the client must process a payment transaction—often via cryptocurrency or a traditional payment gateway—before retrying the request.

How the x402 protocol works

The x402 protocol extends standard HTTP to facilitate machine-to-machine (M2M) payments. It relies on specific headers to communicate payment requirements and status between the client and server.

1
Define the constraint
Name the space, budget, timing, or skill limit that shapes the Pay-Per-API 402 decision.
2
Compare realistic options
Use the same criteria for each option so the tradeoff is visible.
3
Choose the practical path
Pick the option that still works after cost, maintenance, and fallback needs are included.

Setting up your first 402 endpoint

To implement a 402 endpoint, you must configure your server to return a 402 Payment Required status when payment is missing or invalid. The response must include a Pay header containing the payment URI and instructions.

1
Confirm prerequisites
Check compatibility, account access, firmware, network, and physical access before changing the Pay-Per-API 402 setup.
2
Make one change at a time
Apply the setup steps in order so any connection, pairing, or permission failure is easy to isolate.
3
Verify the result
Test the final state from the app and from the physical device before adding automations or optional settings.

Comparing 402 to subscription models

Pay-Per-API 402 works best as a clear sequence: define the constraint, compare the realistic options, test the tradeoff, and choose the path with the fewest hidden costs. That order keeps the advice usable instead of decorative. After each step, pause long enough to check whether the recommendation still fits the reader's actual situation. If it depends on perfect timing, unusual access, or a best-case budget, include a simpler fallback.

FactorWhat to checkWhy it matters
FitMatch the option to the primary use case.A good deal still fails if it does not fit the job.
ConditionVerify age, wear, and service history.Hidden condition issues erase upfront savings.
CostCompare purchase price with likely upkeep.The cheapest option is not always the lowest-cost option.

Fixing common 402 integration errors

When building machine payments, the 402 response is your signal to pause and process. Developers often stumble on the handshake details. Below are the two most frequent pitfalls and how to resolve them quickly.

Verify signatures strictly

APIs often include a digital signature in the response header to prove the price is authentic. If your client doesn't verify this signature against your stored public key, you risk accepting manipulated prices. Treat signature verification as a non-negotiable step before you attempt any payment.

Handle nonce collisions

A nonce ensures each payment request is unique. If your system reuses a nonce, the API will reject the transaction to prevent replay attacks. Always generate a fresh, random nonce for every request. Store the used nonces locally for a short window to detect duplicates before sending.

Check header casing

HTTP headers are case-insensitive, but some implementations are strict. Ensure your code reads the X-Price or X-Payment-Token headers exactly as the API spec defines them. Mismatched casing can cause your parser to miss the payment details entirely.

Fix 402 errors by verifying signatures, generating unique nonces, and checking header casing. These three steps resolve most integration failures.

Verify your 402 implementation

Before pushing to production, run through this checklist to ensure the x402 payment flow is secure and functional. The x402 protocol relies on specific HTTP responses to enable machine-to-machine payments, so any deviation breaks the automation.

  • Test the 402 Response: Send a request without payment credentials. Confirm the server returns a 402 Payment Required status code with a valid Pay header containing the crypto payment URI.
  • Validate Payment Verification: Submit a valid transaction hash. Ensure the server verifies the blockchain confirmation and transitions to a 200 OK response with the expected data.
  • Check Error Handling: Simulate invalid signatures and expired transactions. Verify the server returns appropriate error codes (e.g., 400 Bad Request or 401 Unauthorized) without exposing sensitive internal details.
  • Review Logging: Confirm that payment events, failed attempts, and successful verifications are logged securely for audit purposes without storing private keys or full transaction payloads.

Frequently asked questions about 402