Lumière PayCheck Free API key

Payments on Base + Solana + Keeta

How to Handle the x402 Payment Required Error

· updated · 4 min read

The x402 "payment required" error is a 402 response: the API wants a small payment before it sends the data. To handle it, check that the quote is safe, pay it with an x402 client, and send the request again with the payment attached.

A 402 is not a crash or a timeout. It's the API telling your agent the price. For developers new to x402 this can feel strange, because there's no account, no API key and no invoice. Here's how the flow works, how to check an endpoint before you pay, and what to do when it keeps answering 402 after you've paid.

What the 402 response means

When your agent calls an x402 endpoint without paying, the endpoint answers with status 402 and a quote. The quote tells you:

  • the price,
  • the network (for example Base or Solana),
  • the token (usually USDC),
  • the wallet that gets paid (called payTo).

Your x402 client library reads that quote, signs a payment for exactly that amount, and sends the same request again with the payment in a header. The seller checks the payment, settles it, and returns the data. You never sign up for anything. The payment is the access.

So the 402 itself is normal. It's the first half of every x402 call.

Check the endpoint before you pay

Paying a wallet you've never seen is a risk. A payout wallet can be swapped by an attacker, a price can jump, and some endpoints take the money and send back nothing useful. Lumière PayCheck monitors the endpoints listed in the x402 Bazaar (more than 130,000) and checks each one: is the 402 quote valid, are the price and payout wallet stable, does it answer. It also makes real paid test calls to confirm an endpoint delivers what it advertises.

There are three easy ways to check:

  1. By hand: go to https://lumierepaycheck.org/check, paste the endpoint URL, and see its grade (A to F), verdict and payout wallet history.
  2. Quick grade from code: GET /v1/score?url=<endpoint> returns a 0 to 100 score and a verdict: proceed, caution or avoid. It's free.
  3. Right before paying: send the url, amount and payTo from the 402 quote to POST /v1/check-payment. It answers allow true or false, with the reasons. Pay only when allow is true.

If your agent uses MCP, the same checks are the check_endpoint and check_payment tools on PayCheck's free MCP server.

Still getting 402 after you paid?

This is the most common way an x402 call goes wrong. In our own paid tests, a payment that didn't go through is the most frequent bad result (live numbers at https://lumierepaycheck.org/reliability). Usually no money moves, but your agent gets nothing back. Check these, in order:

  • Did the payment header get sent? If you call the endpoint with a plain HTTP client instead of an x402 client, nothing is attached, and you'll get the same 402 every time.
  • Did you pay what the quote asked? The amount, network, token and payTo must match the quote exactly. A payment on the wrong network or to an old wallet is rejected.
  • Did you use the method the listing declares? If the listing says GET and you send POST (or the other way around), some servers return the quote again instead of reading your payment.
  • Is it the seller's bug? Some servers send the 402 before they ever look at the payment, so every paid call loops. If the second 402 is exactly the same as the first, the server probably never read your payment. Check the endpoint's grade on PayCheck: if our paid test shows "asked for payment again", the problem is on the seller's side.

Confirm you got what you paid for

A 402 quote shows the price, and a payment shows that money moved. Neither proves the data was right. That's why PayCheck makes small real test payments and checks that the answer matches what the listing promises.

Every paid test PayCheck makes comes with a receipt signed with an Ed25519 key, so anyone can verify it. You can see them at GET /v1/test-receipts?url=<endpoint>, free. Sellers can also fund a paid test of their own endpoint (the money goes back to their payout wallet) and show a live badge.

After your own agent pays, report how it went with the report_outcome MCP tool or POST /v1/report: did a response arrive, did it match the listing, was the data usable. Those reports make the grades better for everyone.

FAQ

What causes the x402 payment required error? The endpoint wants payment before it returns data. Use an x402 client to pay the quote and resend the request; if you still get 402 after paying, check the header, the amount and network, and the method.

Is Lumière PayCheck free to use? Yes. Scores, verdicts, the payment check, paid-test receipts and the MCP server are free. Paid plans add agent keys with spend limits and audit trails: Builder is $9 a month and Business is $49 a month.

How do I know a seller refunds failed calls? Our public reliability report lists the sellers that refunded failed paid calls in the last 30 days. See https://lumierepaycheck.org/reliability.

Check any x402 endpoint free before your agent pays it: https://lumierepaycheck.org/check

Check an endpoint before your agent pays it. Free grades and allow-or-deny checks: lumierepaycheck.org · Every x402 endpoint, graded · Docs

More from the blog

  • The highest-graded x402 APIs for web search and scraping

    Updated November 21, 2026 from PayCheck's live grades. These are the x402 endpoints for web search and scraping that Lumière PayCheck grades highest right…

  • How to Stop an AI Agent from Paying a Scam API

    To stop an AI agent from paying a scam API, check the seller before every payment and cap what the agent can spend. Lumière PayCheck does the seller check…

  • What Is X402?

    X402 is an HTTP extension that lets APIs ask for payment directly in their responses. An API returns a 402 status code with a price quote and wallet…