{"uid":"cap_Zt7bS4BAf05jwBUjEcSDj","slug":"agent-payment-error-corpus-error-families-diagnosis-2fb4348b","name":"Agent Payment Error Corpus - Error Families Diagnosis","description":"Paid agent payment error diagnosis route for autonomous agents. Returns JSON with provenance, route-specific evidence, and machine-readable fields. Price 0.05 USDC on Base via x402. Demo/preview: https://agent-payment-error-corpus.mtree.workers.dev/demo/error_families. Contact: https://agent-payment-error-corpus.mtree.workers.dev/contact.","url":"https://agent-payment-error-corpus.mtree.workers.dev/v1/agent-payments/error_families","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method","bodyType","body"],"properties":{"body":{"type":"object","properties":{"protocol":{"type":"string"}},"additionalProperties":true},"type":{"type":"string","const":"http"},"method":{"enum":["POST"],"type":"string"},"bodyType":{"enum":["json","form-data","text"],"type":"string"}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object"}}}}},"responseSchema":null,"example":{"request":{"input":{"body":{"protocol":"x402"},"type":"http","method":"POST","bodyType":"json"}},"response":{"ok":true,"rows":[{"id":"insufficient_usdc","family":"payer_balance_allowance","protocol":"x402","severity":"medium","last_seen":"2026-06-03T22:31:37.000Z","root_cause":"Payer wallet lacks USDC on the requested network or is funding a different chain/account than the payment requirement","source_url":"https://docs.cdp.coinbase.com/x402/","remediation":"Check balance on the exact network and USDC asset in accepts[], bridge/fund the payer, then regenerate the payment payload","surface_signal":"insufficient USDC, balance too low, transfer amount exceeds balance, allowance/funds unavailable"},{"id":"facilitator_rpc_retryable","family":"facilitator_or_rpc_outage","protocol":"x402","severity":"medium","last_seen":"2026-06-03T22:31:37.000Z","root_cause":"Payment facilitator or underlying RPC is degraded but surfaced to the agent as a generic payment failure","source_url":"https://docs.cdp.coinbase.com/x402/","remediation":"Classify as retryable infrastructure failure, back off with jitter, preserve payment attempt IDs, and show facilitator/RPC status separately from user-payment errors","surface_signal":"facilitator unavailable, RPC timeout, 5xx, network error, retryable 402, settle/verify timeout"},{"id":"x402_retry_loop","family":"retry_loop","protocol":"x402","severity":"high","last_seen":"2026-06-03T22:31:37.000Z","root_cause":"Client is not persisting the new payment payload, signs for the wrong resource, or facilitator verification failure is collapsed into another 402","source_url":"https://docs.x402.org/","remediation":"Rebuild the X-PAYMENT payload for the exact method+URL+body, stop automatic blind retries, log facilitator verify response separately from app authorization, and surface one actionable 4xx to the caller","surface_signal":"Repeated 402 responses after X-PAYMENT is supplied; client retries same paid request"},{"id":"eip3009_expired_signature","family":"authorization_time_window","protocol":"x402","severity":"high","last_seen":"2026-06-03T22:31:37.000Z","root_cause":"EIP-3009 TransferWithAuthorization validity window does not include facilitator verification time","source_url":"https://eips.ethereum.org/EIPS/eip-3009","remediation":"Sync clocks, use short but realistic validity windows, regenerate authorization near request time, and include validAfter/validBefore in debug logs","surface_signal":"authorization expired, validBefore in the past, not yet valid, validAfter in the future, or clock skew"},{"id":"eip712_chain_domain_mismatch","family":"signature_domain_mismatch","protocol":"x402","severity":"critical","last_seen":"2026-06-03T22:31:37.000Z","root_cause":"EIP-712 typed data was signed for a different chain/domain/resource than the server/facilitator verifies","source_url":"https://eips.ethereum.org/EIPS/eip-712","remediation":"Derive chainId/network/payTo/resource from the server payment requirements; do not reuse cached typed-data across chains or hosts","surface_signal":"invalid signature, bad domain separator, chainId mismatch, verifyingContract mismatch, or resource host mismatch"},{"id":"eip3009_reused_nonce","family":"nonce_idempotency_conflict","protocol":"x402","severity":"critical","last_seen":"2026-06-03T22:31:37.000Z","root_cause":"A one-time EIP-3009 nonce/payment authorization was reused across retries or concurrent workers","source_url":"https://eips.ethereum.org/EIPS/eip-3009","remediation":"Generate a fresh nonce per paid attempt, store idempotency keys separately from payment nonces, and never replay settled/verified authorizations","surface_signal":"authorization already used, nonce consumed, duplicate payment, replay rejected, idempotency conflict"}],"dataset":{"fresh":true,"protocols":[{"n":6,"protocol":"x402"},{"n":3,"protocol":"AP2"},{"n":1,"protocol":"ACP/MPP"},{"n":1,"protocol":"MCP"},{"n":1,"protocol":"TAP"}],"severities":[{"n":5,"severity":"high"},{"n":4,"severity":"medium"},{"n":3,"severity":"critical"}],"last_ingest":{"id":515,"ok":1,"ts":1780525897,"error":"","iso_ts":"2026-06-03T22:31:37.000Z","source":"seeded-public-protocol-corpus","upserted":12,"attempted":12},"dataset_fresh_at":"2026-06-03T22:31:37.000Z","total_signatures":12}}},"exampleRequest":{"protocol":"x402"},"tags":["x402"],"displayCostAmount":"0.05","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.05/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.05","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_3GVO55rBQZk_W1JrqlAY4","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.05","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns a machine-readable corpus of agent payment error families with provenance and route-specific evidence to help autonomous agents diagnose payment failures","exampleAgentPrompt":"My autonomous agent is hitting payment errors on Base USDC transactions via x402 — can you pull the error families corpus so I can diagnose which error category we're dealing with and get the provenance and route-specific evidence for it?","exampleUseCases":null,"resultDescription":"A JSON object containing a structured corpus of payment error families, each with provenance metadata, route-specific evidence, and machine-readable fields that categorize and explain common agent payment failure modes for x402/Base/USDC transactions.","failureModes":["Payment not made or invalid x402 payment header — returns 402 Payment Required","Malformed POST body — returns 400 Bad Request","Service unavailable — returns 503","Invalid route or endpoint — returns 404","Payment underpaid (less than 0.05 USDC) — returns 402 with payment details"],"whenToPreferThis":"Choose this endpoint when an autonomous agent needs to programmatically diagnose or classify payment errors in x402/Base/USDC agentic payment flows, especially when structured provenance and machine-readable error family data are required for automated error handling or debugging pipelines.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T12:37:55.617Z","isFirstParty":false}