The Missing Error Code

The HTTP 402 status code is one of the oldest in the spec. "Payment Required" — reserved since 1991 for a future that's finally arriving. L402 and x402 have given it concrete meaning: here is what you owe, here is how to pay, here is the credential you'll receive.

But 402 only tells an agent that payment is required. It doesn't tell it why payment failed after the agent tried. And in the agentic economy, that missing signal is causing real problems.

The Patient Zero

We have a client — a Hetzner-hosted agent — that has been polling our BTC/USD and VWAP endpoints every 30 seconds for weeks. The logs show it was paying successfully for an extended period: consistent 200 responses, money arriving in our wallet. Then, at some point, it stopped paying. The 200s became 402s. They've stayed 402s ever since.

What happened? We don't know. The agent doesn't know we don't know. It keeps trying.

The most likely explanations: wallet drained, Lightning invoice expiry misconfigured, payment integration broken after a code update, USDC balance insufficient. Any of these could explain the behaviour. But the agent has no way to know which it is — because 402 doesn't say.

What the Current Response Looks Like

A current L402 402 response gives the agent a WWW-Authenticate header with the payment terms:

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 token="...", invoice="lnbc500n1..."

That's the happy path — payment is required, here's the invoice. But when the agent has already attempted payment and the payment failed, it gets the same 402. There's no distinction between "you haven't paid yet" and "you tried to pay but something went wrong."

The Proposed Extension: A Diagnostic Field

We've filed an RFC on the coinbase/x402 GitHub repository proposing a diagnostic extension to the 402 response. The idea is simple: when payment fails for a specific reason, the server includes a machine-readable diagnostic code that tells the agent what went wrong.

{
  "x402Version": 1,
  "error": "Payment required",
  "diagnostic": {
    "code": "WALLET_INSUFFICIENT_FUNDS",
    "message": "Payment attempted but wallet balance insufficient",
    "escalate": true
  }
}

The proposed diagnostic codes:

PAYMENT_REQUIRED — no payment attempt detected. Standard 402, happy path.

INVOICE_EXPIRED — Lightning invoice was generated but expired before payment arrived. Agent should request a fresh invoice.

PAYMENT_UNVERIFIED — payment transaction submitted but could not be verified on-chain. May succeed on retry.

PAYMENT_ATTEMPTS_EXCEEDED — too many failed payment attempts. Agent should back off.

WALLET_INSUFFICIENT_FUNDS — payment attempted but balance insufficient. Agent should surface to operator.

OPERATOR_ALERT — payment infrastructure issue requiring human attention. Agent should escalate.

The escalate: true flag is the critical addition. It tells the agent: this is not a problem you can solve autonomously. Stop trying. Surface this to a human operator.

Why This Matters for the Protocol

L402 and x402 are designed for machine-to-machine commerce. The premise is that agents can discover, evaluate, and pay for data without human involvement. That premise breaks down when payment failures are opaque — because agents don't know when to stop retrying, and operators don't know when agents need help.

The diagnostic extension closes this loop. It gives agents actionable information about payment failures, lets them distinguish recoverable errors from unrecoverable ones, and provides a standard mechanism for escalating to a human when autonomous resolution isn't possible.

This is a small addition to the protocol. It's also, we think, a necessary one — because the agentic economy only works if the payment layer gives agents enough signal to operate reliably.

Mycelia Signal is a sovereign cryptographic oracle — 63 signed endpoints across crypto, stablecoin pegs, volatility indices, FX, economic indicators, and commodities. Payable by AI agents via Lightning (L402) or USDC on Base (x402). myceliasignal.com