Payment Error Codes for Agent API Calls

Payment error codes for agent API calls turn failed paid requests into useful next steps. When an AI agent pays for an API result, a vague error such as "payment failed" is not enough. The agent needs to know whether it should refresh payment terms, retry with proof, use a different wallet, stop because the endpoint is unavailable, or report the issue to a human.

This matters because paid agent APIs are request-driven. An agent may call an endpoint, receive an `HTTP 402 Payment Required` response, pay in USDC on Base, and retry with payment proof. If any part of that loop fails, the API should explain the failure in a form software can evaluate.

Apiosk is built for this operating model: get paid by AI, expose x402-style payment requirements, accept crypto in and support euros out, preserve non-custodial seller controls, bundle micropayments, and keep records that make reconciliation possible.

Why generic errors are not enough

Traditional API errors often assume a human developer is nearby. A dashboard can say a card was declined, an account was inactive, or a subscription needs attention. Agent payments are different because the buyer may be an autonomous workflow deciding what to do within seconds.

If an agent receives only `400 Bad Request`, it cannot tell whether the payment proof was malformed, the quote expired, the wrong chain was used, the seller paused the endpoint, or the request already succeeded under the same idempotency key. Each case requires a different action.

Payment-specific error codes help the agent avoid wasteful retries. They also help sellers reduce support noise. When finance or support reviews a paid call later, the error code can connect the request, quote, proof, wallet activity, settlement status, and reconciliation record.

Keep HTTP status and payment reason separate

HTTP status codes should still do their job. A protected endpoint can use `402 Payment Required` when payment terms are needed. It can use `409 Conflict` for an idempotency mismatch, `422 Unprocessable Entity` for malformed proof, or `503 Service Unavailable` when the paid service is paused.

The payment reason should be a structured field inside the response. For example, an API might return `quote_expired`, `wrong_network`, `insufficient_amount`, `proof_not_found`, `proof_already_used`, or `settlement_under_review`.

That separation keeps the protocol easy to understand. Humans and infrastructure can read the HTTP status. Agents, wallets, and gateways can use the payment reason to choose a recovery path.

Error codes agents can act on

Good payment errors should map to clear behavior. If the agent can recover, the response should say how. If it cannot recover automatically, the response should make that clear.

Useful recoverable codes include:

• `quote_expired`: Request a fresh payment requirement before paying.
• `wrong_network`: Use the required network, such as Base, instead of another chain.
• `wrong_asset`: Pay with the accepted token, such as USDC.
• `insufficient_amount`: Pay the exact required amount or request a new quote.
• `missing_payment_proof`: Retry with proof after payment is confirmed.
• `proof_pending`: Wait briefly and retry with the same idempotency key.
• `idempotency_replay`: Treat the earlier successful request as authoritative.

Useful non-recoverable or human-review codes include:

• `endpoint_not_payable`: The endpoint is not currently enabled for paid access.
• `buyer_not_allowed`: The caller is not eligible to pay for this action.
• `payment_destination_changed`: Refresh terms before attempting any payment.
• `proof_rejected`: Do not reuse this proof; request new terms or escalate.
• `settlement_blocked`: The seller must review the payment before settlement.

The exact names can vary, but the behavior should be predictable. Agents should not guess whether paying again is safe.

Include context without leaking internals

A payment error response should include enough context for recovery, but not private operational details. The agent does not need internal fraud notes, bank references, or seller accounting configuration. It does need the identifiers required to continue safely.

Practical fields include:

• Error code and short message.
• Payment requirement or quote identifier.
• Endpoint or paid action identifier.
• Expected token and network.
• Expected amount, when safe to repeat.
• Expiration timestamp for current terms.
• Idempotency key status.
• Retry guidance, such as `retry_after_seconds`.
• Documentation or support reference.

For Apiosk sellers, this context can also preserve the trail from payment attempt to settlement. A failed proof, expired quote, or held payment should be visible later as part of the paid request history.

Protect against duplicate paid work

Many payment errors happen during retries. An agent may submit proof, lose the HTTP response, and retry. The seller may see the same proof twice. The upstream API may complete work before the client receives the result.

Structured payment errors should distinguish duplicate proof from duplicate work. If the same idempotency key already produced a successful result, the response should tell the agent to reuse or retrieve that result. If the proof was already used for a different paid action, the response should reject it.

This is critical for micropayments. Small paid calls can happen frequently, and retry behavior must not create accidental double execution or double charging. A clean idempotency record is as important as the payment proof itself.

Tie failures to seller operations

Payment error codes are not only for agents. They are also operational labels for the seller. A spike in `wrong_network` errors may mean documentation is unclear. Frequent `quote_expired` errors may mean quote lifetimes are too short for the buyer workflow. Repeated `proof_pending` states may indicate confirmation timing issues.

These labels also help reconciliation. If a payment arrived but fulfillment failed, the seller needs to know whether the amount should be held, refunded, excluded from a bundle, or reviewed before euro settlement. A wallet transaction without the request context is hard to explain. A payment error record linked to the quote, proof, endpoint, and buyer is much more useful.

Apiosk's value is not just accepting USDC on Base. It is helping sellers connect paid API activity to the business workflow that follows: bundling small payments, tracking settlement eligibility, and producing records that finance teams can reconcile.

Example: an expired x402 quote

Imagine an agent calling a paid company enrichment endpoint. The endpoint returns an x402-style payment requirement for one enrichment, priced in USDC on Base, with a short expiration window. The agent waits too long, then pays and retries with proof.

The gateway sees that the proof relates to expired terms. A vague failure would leave the agent uncertain. A useful response says `quote_expired`, references the old quote, marks the proof status, and tells the agent whether it should request a fresh quote or contact the seller.

If the payment was received after expiration, the seller also needs a record for review. The operations team can see the old quote, payment proof, timestamp, fulfillment status, and whether the payment entered a settlement exception path. That is the difference between a confusing wallet event and a manageable paid API workflow.

A practical design checklist

Before launching a paid endpoint for agents, review the failure surface:

• Can the agent tell whether payment is needed, invalid, pending, or rejected?
• Are expired quotes different from malformed proof?
• Are wrong token and wrong network errors explicit?
• Does every retry path preserve an idempotency key?
• Can duplicate proof be detected without running paid work twice?
• Are held or rejected payments visible in settlement records?
• Can support teams trace an error code back to request and payment context?

The goal is not to invent a complicated error taxonomy. The goal is to make the next action clear.

How Apiosk sellers should think about errors

Every paid API call has two audiences: the software buyer trying to complete a task and the business that must account for the payment. Payment error codes serve both.

For agents, they turn failure into safe behavior. For sellers, they create cleaner records around x402 requirements, USDC payments, endpoint execution, micropayment bundles, euro settlement context, and reconciliation. That makes agent commerce easier to automate without making the payment path opaque.

Start with a small set of codes, document what each one means, and keep the identifiers consistent from request to settlement. That is enough to make paid API failures understandable to agents, developers, support teams, and finance.