Agent payment errors are the failure modes that surface when an AI agent tries to authorize, sign, or settle a charge through a machine-payments rail like x402, ACP, AP2, MPP, or Visa TAP. They show up as HTTP 401, 402, 409, 502, and 504 responses, as on-chain reverts on EIP-3009 nonces, as AP2 mandate verification failures, and as MCP tool-unavailable callbacks. This piece is the troubleshooting reference: every common error category with the underlying mechanism, the root cause, the fix, and a prevention pattern. Stripe, Coinbase, and Visa publish quickstart guides; this is what a developer lands on when an agent integration breaks at 2 a.m.
​

AI agent payment errors are structured failure responses that machine-payments protocols return when a request cannot be authorized, signed, or settled. They span HTTP status codes (401, 402, 409, 502, 504), on-chain reverts (EIP-3009 nonce collisions, expired signatures), protocol-level verification failures (AP2 mandates, TAP directory misses), and tool-layer errors (MCP server unavailability). Each has a known mechanism and known fix.
​

The error surface widened sharply between late 2025 and early 2026 as five protocols shipped in parallel: ACP on September 29, 2025; Visa TAP on October 14, 2025; Stripe's x402 integration on February 10, 2026; Coinbase Agentic Wallets on February 11, 2026; and Stripe and Tempo's MPP on March 18, 2026. Each introduced its own error vocabulary on top of HTTP and EVM error surfaces.
​

The errors fall into roughly nine families: authentication failures, signature mismatches, expired or malformed mandates, gas underestimates, idempotency conflicts, webhook retry storms, mandate scope mismatches, directory misses, and MCP tool-availability errors. A given production failure often combines two or three. A 402 retry loop is usually a 402 (payment required) plus a signature-mismatch 401 plus a clock-skew validity-window error stacked together. Traditional web-app monitoring assumes 402 is rare and 401 means a stale token; in agent-payment workloads, 402 is a normal handshake step and 401 may mean the EIP-712 typed signature canonicalized against the wrong domain separator.
​

Agent payment errors surface through three signal layers: HTTP status codes with structured JSON payloads, on-chain transaction reverts with revert reasons, and protocol-specific telemetry from facilitators like Stripe, Coinbase Commerce, or AP2 mandate verifiers. Each layer carries a different field set, and triage typically follows the request from outermost (HTTP) to innermost (chain) until the failing component is identified.
​

At the HTTP layer, the first signal is the status code. The five most common in agent-payment traffic are 401 (signature problem), 402 (the normal x402 handshake), 409 (idempotency-key collision or nonce reuse), 502 (facilitator or RPC outage), and 504 (slow chain finality or facilitator queue backup). The body almost always includes a structured JSON payload with an error code, a human-readable message, and protocol-specific fields like payment_requirement, x402_version, or requestId. Stripe's error reference documents the shape for ACP and MPP; Coinbase's x402 docs document the x402 error envelope.
​

At the chain layer, the signal is a transaction revert with a revert reason. EIP-3009's transferWithAuthorization reverts with strings like FiatTokenV2: authorization is expired, FiatTokenV2: authorization is not yet valid, or FiatTokenV2: authorization is used or canceled. The first two are clock-skew or validity-window problems; the third is a nonce collision or a previously cancelled authorization. Permit2 reverts with InvalidSignature, InvalidNonce, SignatureExpired, or AllowanceExpired for the same conditions on non-3009 stablecoins. The revert reason is the most useful signal in chain-layer debugging; a tx hash without the reason just tells you it failed.
​

At the protocol-telemetry layer, the signal varies by protocol. AP2 mandate verifiers return a typed verification_result object distinguishing signature-invalid, mandate-expired, mandate-out-of-scope, and identity-provider-unreachable failures. Visa TAP verifications return an RFC 9421 verification status code plus a directory-lookup status. MCP servers return tool-availability errors with a tool ID and a reason. Stripe's MPP and ACP webhooks emit typed events (payment_intent.payment_failed, payment_intent.requires_action) with last_payment_error objects that carry the canonical decline reason. The HTTP body says what failed at the wire, the chain revert says what failed on settlement, the protocol telemetry says what failed at the verification step in between.
​

The nine categories below cover the bulk of production agent-payment failures observed across x402, ACP, AP2, MPP, TAP, and MCP integrations through April 2026. Each entry pairs the surface signal (HTTP code or revert string) with the underlying mechanism, the typical root cause, and the fix. The comparison table later in the section consolidates them for quick reference.
​

A 401 from an x402-enabled endpoint almost always means the signature in the X-PAYMENT header did not verify against the agent's expected wallet. The most common cause is a domain-separator mismatch in EIP-712: the agent signed against chain ID 1 (Ethereum mainnet) when the facilitator expected chain ID 8453 (Base), or signed against the test USDC contract instead of the production one. Fix by inspecting the typed-data domain and comparing every field — name, version, chainId, verifyingContract — against the contract the facilitator settles on. The EIP-712 spec defines canonical hashing. The second cause is signing with the wrong key — an operator running multiple wallets (browse, pay, top-up) can sign a payment with the browse-only key. Fix by scoping signing keys per intent (Visa TAP's agent-browser-auth vs agent-payer-auth tag pattern is the right model) and surfacing the recovered signer address in the 401 body.
​

Signature mismatches at the chain layer manifest as InvalidSignature reverts when the facilitator submits the signed payload. The mechanism is the same as the 401 case but caught one step later: the EIP-712 hash the contract computed does not match the hash the agent signed. The most common cause beyond domain mismatch is canonical-encoding drift — the agent serialized the typed payload in a different field order, or with a different EIP-2098 compact-signature encoding, than the contract expects. Use the Permit2 reference implementation as the canonical encoder for non-USDC stablecoins, and use a single shared library on both sides. A third pattern: hardware wallets that prepend an Ethereum-signed-message prefix to typed data and emit a personal_sign-style signature for EIP-712 payloads. Fix by upgrading to a client that supports eth_signTypedData_v4 natively or routing typed-data signing through a dedicated agent wallet provider like Coinbase's Agentic Wallet.
​

AP2 mandates are cryptographic signatures over a structured JSON payload that names a user, an agent, a merchant, a maximum amount, and a validity window. Verification failure surfaces as a typed event with verification_status: expired, verification_status: out_of_scope, or verification_status: invalid_signature. Expired mandates are a clock-management problem; align clocks against NTP and issue mandates with conservative validity windows (15 minutes is a conservative default observed in AP2 reference implementations). Out-of-scope failures mean the agent tried to charge a merchant or amount the mandate did not cover; re-issue with correct scope rather than retrying. Invalid-signature failures typically mean canonical-JSON drift between signer and verifier (key order or whitespace) — use the AP2 reference canonicalizer on both ends.
​

x402 settlement is gasless on the agent side; the facilitator submits the on-chain transaction and pays gas. Gas underestimates show up as facilitator telemetry (tx_status: out_of_gas or tx_status: reverted) rather than an HTTP error to the agent. The most common cause is a gas-price spike between agent submission and block inclusion. Coinbase's x402 facilitator and Stripe's MPP settlement use EIP-1559 dynamic fees, but custom facilitators sometimes hard-code a gas-price ceiling that breaks under load. Less commonly, EIP-3009 reverts because the authorizer's USDC balance dropped below the authorized amount between signing and submission. Check the balance pre-submit and return a structured error rather than burning gas on a guaranteed revert. The USDC supply of $77.3 billion (late April 2026) means most agents have no balance issue, but agents holding USDe ($3.8B) or PYUSD ($3.4B) sometimes do.
​

Idempotency conflicts surface as HTTP 409 indicating the idempotency key has already been used for a different request. The facilitator hashes the request body keyed by the idempotency key and returns a conflict if a new request reuses the key with different content. The cause is almost always a retry loop where the agent's HTTP client mutated the request body (header added, timestamp refreshed) while reusing the key. Fix by treating the idempotency key as content-bound: hash the canonical request body to derive it. Stripe's idempotency key docs detail the semantics — same key with same body returns the same response, same key with different body returns 409. EIP-3009's nonce field plays the same role at the chain layer; reusing a nonce with a different amount triggers an authorization is used or canceled revert.
​

Stripe's MPP, Coinbase Commerce, and Skyfire all emit webhooks for payment lifecycle events. A retry storm happens when the agent's receiver endpoint returns a 5xx (or times out) and the sender retries with exponential backoff. Stripe retries up to 3 days by default; over a multi-hour outage the receiver can rack up dozens of retries per event. Fix on the receiver by returning 200 immediately on receipt and processing asynchronously; never block on payment business logic before acknowledging. The deeper fix is structural: design handlers to be idempotent at the application layer, keyed on the event ID. The Stripe webhook docs recommend storing every event ID for 7 days and rejecting duplicates; the same pattern works for MPP, ACP, and Coinbase Commerce events.
​

An x402 retry loop is the pathology where the agent receives an HTTP 402, signs and resubmits, receives another 402, and never converges. The three causes: (1) clock skew — the signed validity window is offset from the verifier's clock and every attempt is rejected as expired or not-yet-valid; (2) chain-ID mismatch — agent signs against chain X, facilitator verifies on chain Y, every attempt fails as unauthorized signer; (3) facility downtime — the facilitator's settlement RPC is intermittently failing, returning 402 instead of 5xx. Diagnose by inspecting the X-PAYMENT-RESPONSE headers and the structured 402 body. The Coinbase x402 spec defines a retry-after field and an error_type field that distinguishes "sign and resubmit" from "retryable transient error" from "permanently invalid signature." Fix with a max-retry counter (5) and error-type-aware backoff that bails on permanent errors.
​

ACP (Stripe + OpenAI, shipped September 29, 2025) uses Shared Payment Tokens (SPTs) bound to a merchant ID, max amount, and session window. A scope-mismatch surfaces when the agent presents an SPT against a merchant or amount the token does not cover; Stripe-side verification returns a typed error in the last_payment_error field of the PaymentIntent. The two common causes: the agent cached an SPT past its session window and reused it on a new checkout; or the agent presented an SPT scoped to merchant A on a checkout flow that resolved to merchant B (a marketplace seller hidden under the platform's merchant ID). Fix by treating SPTs as single-checkout-scoped — never reuse, never cache across sessions — and resolve the settlement merchant ID before requesting. ACP's Instant Checkout retired March 24, 2026 after roughly 12 Shopify pilot merchants, but the spec persists through Stripe Link Agent Wallets.
​

Visa TAP signs three HTTP headers (Signature-Agent, Signature-Input, Signature) and merchants verify the Ed25519 signature against a Visa-operated directory of agent public keys. A directory miss surfaces as a verification failure where the merchant cannot find the operator's public key at the URL named in Signature-Agent. The mechanism is RFC 9421 HTTP Message Signatures; the failure mode is a stale or empty cache lookup against the operator's published JWKS-style endpoint.
​

Causes: (1) the operator rotated keys without giving the directory's TTL window time to refresh; (2) the merchant's verification cache is misconfigured and not refreshing on cache miss; (3) the operator's directory endpoint is returning 5xx for transient infrastructure reasons. Fix by implementing the recommended caching pattern from the Visa TAP reference implementation — 60-second refresh window, immediate invalidation on revocation push, stale-while-revalidate semantics.
​

An MCP tool-unavailability error surfaces when the agent invokes a tool an MCP server exposes and the server returns a typed error indicating the tool is not callable. Causes: the server is offline; the tool was removed from the manifest between discovery and invocation; the session lacks scope. Stripe's MCP server exposes payment, customer, and product tools; Coinbase's MCP integrations expose wallet and transfer tools. Fix by treating tool discovery as a per-session contract — re-fetch the manifest before each batch of invocations, surface a typed error to the agent's planner when a tool disappears, and match against capability descriptions rather than hard-coded tool IDs. Anthropic's MCP tools spec documents the patterns.
​

The table below consolidates the nine error categories with their surface signal, mechanism, and primary fix.

A persistent x402 retry loop almost always means one of three conditions is failing on every resubmission: clock skew between the signed payload's validity window and the verifier, a chain-ID mismatch between agent and facilitator, or an intermittently-down facilitator surfacing 402 instead of 5xx. Inspect the structured 402 body for the error_type and retry-after fields before retrying.
​

The 402 retry loop is the most-reported failure pattern in agent-payment support channels through April 2026. Diagnose with three checks. First, log the chain ID and contract address from the EIP-712 domain in your signed payload and compare against what the facilitator documents — Stripe's x402 docs list USDC contracts on Base (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), Solana, and Tempo. Chain-ID drift is the leading cause of a permanent loop. Second, log the signing timestamp and validity-window bounds and compare against the verifier's clock; a DST bug or poorly-synced container clock fails every attempt. Third, parse the 402 body for canonical x402 fields. A real "sign and resubmit" 402 carries a payment_requirement object; a facility-error 402 carries an error_type like facilitator_unavailable or verification_timeout. Bail on error_type: invalid_signature immediately; back off with jitter on error_type: facilitator_unavailable; resign and retry on the bare payment-requirement case up to the max-retry counter.
​

A consistent triage workflow turns an agent-payment failure from a several-hour debugging session into a 15-minute fix in most cases. Run the seven steps in order and log every intermediate result. Most failures resolve at step 3 or step 5; the deep cases requiring chain-layer inspection are step 6 onward, and they are far rarer than the wire-layer cases.
​

Step 1: capture the full request and response. Log the HTTP method, URL, all headers (redact authorization), and the body for both. The structured JSON in the response body is the single most diagnostic artifact; without it triage is guesswork. Step 2: identify the protocol. The error envelope differs between x402, ACP, MPP, AP2, and TAP — confirming which protocol is failing tells you which spec to consult. Step 3: classify the error category. Map the status code and error fields to one of the nine categories above. Most failures stop here.
​

Step 4: check obvious environment factors. Clock skew (run NTP), chain-ID mismatch (log the configured chain ID at startup), API version (Stripe x402 requires the 2026-03-04.preview API version per the official docs), and the facilitator's status page. Step 5: verify the signature offline. Take the signed payload, recover the signer using a standalone EIP-712 verifier, and compare against the agent's expected wallet. If the signer doesn't match, the bug is in the signing path. Step 6: trace the chain-layer settlement. Pull the transaction hash from the facilitator's response, look it up on a block explorer, and read the revert reason. FiatTokenV2: authorization is expired, InvalidNonce, and SignatureExpired each map to specific fixes documented above. Step 7: contact the facilitator with a structured report — the request, the response, the signed payload, the recovered signer, and the chain-layer revert reason. A well-formed ticket with all five artifacts resolves an order of magnitude faster than one with only a screenshot.
​

Prevention is cheaper than debugging. Five patterns, applied at integration time, eliminate the bulk of the failure categories above. These are the patterns observable in production-quality agent-payment integrations through April 2026 — not theoretical best practices but observed deltas between teams that ship cleanly and teams that fight retry loops in production.
​

Pattern 1: canary mandates and signatures. Before a new integration goes live, sign a canary payload with a known-good test wallet and run it through every verification path. The canary catches domain-separator mismatches, canonicalization drift, and clock-skew bugs before they hit a real charge. Pattern 2: structured logging at every protocol layer. Log the HTTP request, the protocol-specific telemetry event, and the chain-layer settlement as separate structured events with a shared correlation ID. The triage workflow runs in minutes when logs are structured and in hours when they are not.
​

Pattern 3: replay tests against recorded production traces. Capture anonymized production request/response pairs and replay them against new integration versions before deploy. Replay tests are the highest-leverage protection against canonicalizer changes silently breaking signatures — a common failure when an integration upgrades its EIP-712 library or Permit2 client. Pattern 4: signature pre-verification on the agent side. Before submitting, verify the signed payload locally with the same canonicalizer the facilitator uses. Failing fast on the agent side is much cheaper than failing at the facilitator and entering a retry loop.
​

Pattern 5: bounded retry budgets and error-type-aware backoff. Every retry loop has a max-retry counter (5 for x402; 3 for webhook receivers; 1 for AP2 mandate verification). Backoff honors retry-after when present and adds jitter. Permanent errors (invalid signature, expired mandate, out-of-scope SPT) bail immediately. The Stripe error-handling guide codifies this for ACP and MPP; the same shape applies to x402, AP2, and TAP. One addendum: alert on retry-rate, not just error-rate. A 10x-baseline retry-rate alert catches facility outages and clock-skew drift before they become customer-visible.
​

Eco operates as a stablecoin execution network across 15 chains, abstracting routing, solver selection, and finality so an agent's payment intent settles where the merchant accepts funds. That cross-chain layer eliminates a class of agent-payment errors — chain-ID mismatches, balance drift between signing and settlement, bridging-related signature replay — by collapsing multi-chain reality behind a single intent surface.
​

Stripe's x402 settles on Base, Solana, and Tempo. Coinbase Commerce settles on Base, Solana, and a handful of other Coinbase-supported chains. Visa TAP is rail-agnostic. Agent treasuries do not always live on those chains. Stablecoin supply is roughly $318 billion (per DeFiLlama, late April 2026), with USDT at $189.5 billion heavily on Tron and BSC, USDC at $77.3 billion spread across more than ten chains, and meaningful PYUSD, USDe, and GHO supply on additional networks. Eco handles the cross-chain leg through Hyperlane messaging and Circle's CCTP transport, so an agent on Arbitrum settling into a Tempo-only MPP endpoint never has to write the bridging logic that creates new error surfaces.
​

Sources and methodology. Protocol launch dates verified against issuer press releases. HTTP status code semantics verified against RFC 9110 and protocol-specific docs. EIP references verified against eips.ethereum.org. Stablecoin supplies pulled from DeFiLlama on April 29, 2026. Figures refresh quarterly.
​