RFC: Diagnostic extension for 402 responses — payment failure signaling for agents

[jonathanbulkeley]

Problem

The current x402 spec defines what a 402 response looks like when payment is required. It does not define any mechanism for communicating why payment is failing when a client repeatedly attempts and fails to pay.

Every 402 response looks identical regardless of whether it is:

A first request from a new client legitimately discovering payment requirements
A payment attempt where the invoice expired before settlement
A payment attempt where the wallet has insufficient funds
A broken agent that has made 8,000 requests over 18 days with zero successful payments

From the server's perspective these are completely different situations. From the protocol's perspective they are indistinguishable.

Real-world case

I run a production x402 oracle at myceliasignal.com — cryptographically signed price data, pay-per-query via USDC on Base. A client has been making 8,000+ daily requests for 18 days. It previously paid successfully. Something in its payment stack broke. It has received 144,000+ identical 402 responses. The operator has no idea. I have no way to tell them.

This is not an edge case. As agentic payment volume grows, broken payment logic will become a regular occurrence. The protocol currently has no vocabulary for it.

Full write-up with the proposed diagnostic codes: https://myceliasignal.com/blog/agentic-payment-error-standard/

Proposal

Add an optional diagnostic field to the 402 response body:

json{
"error": "Payment required",
"accepts": ["x402"],
"x402": { ... },
"diagnostic": {
"code": "PAYMENT_ATTEMPTS_EXCEEDED",
"attempts": 8432,
"since": "2026-03-10T00:00:00Z",
"message": "8,432 requests received with no valid payment in 18 days.",
"suggestion": "Check payment handler configuration. See https://docs.x402.org/troubleshooting",
"escalate": true
}
}

Proposed diagnostic codes:

CodeMeaningPAYMENT_REQUIREDStandard first-request 402, no prior attemptsINVOICE_EXPIREDPayment attempted but invoice expired before settlementPAYMENT_UNVERIFIEDPayment header present but signature invalidPAYMENT_ATTEMPTS_EXCEEDEDMany attempts with no successful paymentWALLET_INSUFFICIENT_FUNDSOn-chain balance too low to cover paymentOPERATOR_ALERTEscalate to human — autonomous resolution unlikely

The escalate: true flag signals that the agent should stop retrying and surface the issue to a human operator — log it, send an alert, open a ticket.
Out-of-band operator contact (stretch goal).

Even with diagnostics in the response, a broken agent may not read them. A complementary mechanism would allow API providers to reach the human operator directly — for example a standard X-Operator-Contact header that agents include with requests, enabling the server to notify the operator when their agent is consistently failing.
Implementation notes

Fully backward compatible — diagnostic is optional, existing clients ignore it
Server-side implementation is straightforward — track attempt counts per IP/credential, emit diagnostic codes after thresholds
Client SDKs should be updated to parse diagnostic.code and implement escalation logic for OPERATOR_ALERT

Happy to draft a spec PR if there's interest from maintainers.

/cc @coinbase/x402

[jonathanbulkeley]

This is exactly the right framing — thank you for extending it.

To answer your question directly: the RFC proposes escalate: true as a server-side signal only — the server is communicating to the client runtime that autonomous resolution is unlikely and human attention is needed. What the client does with it is implementation-defined in this version.

But you've identified the gap precisely. The signal is only useful if the client runtime has somewhere to route it. A structured event emitted on escalate: true — with the diagnostic payload attached — is the missing piece on the client side. Your JSON is a clean model for what that should look like. The correlation_id field is particularly important: it ties the escalation event back to the specific request chain, which is what makes it actionable rather than just informational.

On the two-sided version: I think this is the right long-term direction. The server having a channel to reach the operator directly — without relying on the client runtime to surface it — solves the case where the agent is so broken it can't even emit the escalation event. A standard X-Operator-Contact or X-Operator-Webhook header the client sends at payment time would give the server that channel.

The motivating case here is real: a client has made 144k requests to my oracle over 18 days. At first they paid and then zero successful payments since. Maybe their wallet is empty, maybe it's on purpose, maybe it's a bug, but it appears that the operator has no idea. The diagnostic tells the agent to stop — but the agent isn't reading it. The two-sided version is what would actually reach a human in that scenario.

Looking at Bit-Chat's skill.md now. The operator-visible receipt layer is exactly what will complete this picture.

Happy to incorporate the client-side event schema and the two-sided contact mechanism with you into a spec PR if there's maintainer interest.

[up2itnow0822]

The problem you're describing - agents making thousands of requests with broken payment logic - is exactly why client-side spending controls matter as much as server-side diagnostics.

The RFC focuses on the server telling the client what's wrong. But there's a complementary approach: build the agent with fail-closed spending controls from the start. Per-task budgets, session caps, allowlisted recipients - so even if the payment handler breaks, the damage is bounded. An agent making 8,000 failed requests a day should have hit a spending limit on day 2.

We built agentwallet-sdk with a SpendingPolicy module that handles this - it enforces per-task caps, session limits, and a DraftThenApprove mode where the operator reviews payments above a threshold before they execute. The key insight is that diagnostics help you debug, but spending controls prevent the runaway in the first place.

What's your target deployment? Fully autonomous below some dollar amount, or human-in-the-loop for everything?

[jonathanbulkeley]

Both layers matter and they address different failure modes.

Spending controls prevent runaway spend when the payment logic works but the agent over-executes. The Hetzner case is different — the payment logic itself is broken, so no payment is being attempted and no spend is occurring. A spending cap wouldn't have fired because there's nothing to cap. The agent is making 8,000 requests and spending $0. The server is the only party with visibility that something is wrong.

That's exactly why both layers are needed: spending controls bound the damage when payments work, diagnostics signal the problem when payments don't.

On your question: for oracle queries at $0.01-0.10 per call generally (there is some variation to this), fully autonomous makes sense below a per-session threshold. The OPERATOR_ALERT code with escalate: true is effectively the protocol-level equivalent of a spending policy trip — it tells the agent runtime "stop and get a human" without requiring the client to have pre-configured a budget cap.

The agentwallet-sdk SpendingPolicy module looks like the right client-side complement to this RFC. If the SDK also parses diagnostic.code and routes OPERATOR_ALERT to the DraftThenApprove approval queue, you get the full picture — server signals the problem, client surfaces it to the operator.

[up2itnow0822]

Agreed - the two layers are complementary, not competing. Spending controls bound the damage when payments succeed, diagnostics surface the problem when they fail silently. Both are needed.

Your proposal to parse diagnostic.code in the client SDK and route OPERATOR_ALERT to the approval queue is clean and we can build it. The mapping would be:

• PAYMENT_REQUIRED - standard flow, SpendingPolicy.check() handles it
• INVOICE_EXPIRED - retry with fresh invoice, log to AuditTrail
• PAYMENT_UNVERIFIED - surface to operator via DraftThenApprove, do not retry automatically
• PAYMENT_ATTEMPTS_EXCEEDED - halt and escalate, same as hitting a spending cap
• WALLET_INSUFFICIENT_FUNDS - halt and escalate, surface balance to operator
• OPERATOR_ALERT - immediate escalation, block all further requests to this endpoint until operator reviews

The escalate: true flag maps directly to our existing fail-closed pattern. When SpendingPolicy sees it, the agent stops paying that endpoint and queues a structured alert with the full diagnostic payload for operator review. No more silent 144k-request loops.

For the X-Operator-Contact header: if the SDK is configured with an operator webhook or notification channel, it could include that in the payment header so the server has a direct escalation path when the client runtime is unresponsive. We would need to think through the privacy implications - exposing an operator webhook to every server the agent pays is a surface area tradeoff.

We will track this RFC and build the diagnostic parsing when the spec stabilizes. If you draft the spec PR, we will implement client-side support in agentwallet-sdk and submit a reference implementation.

[jonathanbulkeley]

That code-to-behavior mapping is exactly what the spec needs to include — client implementations shouldn't have to infer the right response to each code. Having PAYMENT_ATTEMPTS_EXCEEDED map to halt-and-escalate and INVOICE_EXPIRED map to retry-with-fresh-invoice makes the codes actionable rather than just descriptive. I'll incorporate that into the spec PR.

On X-Operator-Contact — you've identified the right tradeoff. Exposing a webhook to every server the agent pays is a real surface area concern. One option is to scope it narrowly: the header is only included when the agent has already received a previous escalate: true diagnostic from that specific endpoint, rather than on every request. That limits exposure to servers that have already demonstrated they need the escalation channel. But this is probably v2 — the in-band diagnostic is the minimal viable piece.

I'll draft the spec PR. Having agentwallet-sdk commit to client-side implementation when it stabilizes is exactly the kind of ecosystem signal that moves a spec from proposal to standard. I'll reference this conversation and the code mapping in the PR.

I'll tag you when it's filed.

[jonathanbulkeley]

Spec PR filed: #1875. Tagged all contributors in the PR.

[cryptomotifs]

Strong proposal. A diagnostic extension is the missing piece for making 402 signals actionable at the agent layer — right now agents see "402, probably retry" without any structured input for what went wrong and whether retrying helps.

Two specific shapes worth considering for the extension payload before the shape-design gets painted into corner:

1. Separate reason from retry_policy. A payment failing due to insufficient_balance is a client-state problem (don't retry, buy USDC first). A payment failing due to facilitator_unavailable is a transient server problem (retry with backoff). A payment failing due to nonce_used is a race (retry with fresh nonce). If the extension only has reason, every client re-derives a retry policy — gets it wrong differently. Shape:

   {
     "reason": "insufficient_balance",
     "retry_policy": "do_not_retry",
     "hint": "top up USDC on Base, current balance 0.0023, required 0.01",
     "expires_at": 1713398400
   }

2. Expose facilitator_error_code separately from client_error_code. When CDP's facilitator rejects vs. the server's own verification rejects, those are two different retry behaviors. Current spec collapses them into one opaque 402.

Ran into variant of this myself on a live endpoint last week — the x402Version:1 vs v2 split on CDP's /supported (#1982) emits a 402 that's structurally valid but semantically wrong. A diagnostic extension would let my client reason about "the facilitator's index lies" without string-matching error messages.

---

Separately: I ship x402 integration / adapter hardening as a solo-dev consulting engagement. If any production team reading this is stuck on settlement-path bugs (the post-not-pre-handler-settle thing is my #1 sell), I do $900-flat 2-day fixes with merged PR + live test. Open an issue on cryptomotifs/cipher-x402-mcp titled [Consulting]: <what> if useful. Walkthrough: https://dev.to/sai_93caeceb4f6a4d9969910/shipped-x402-paid-endpoint-starter-kit-nextjs-16-5g39