> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Which payment and capture failures to retry with the same idempotency key, and which to stop on.

Retry only when the contract says the same order and the same key are safe. A new idempotency key on a payment that already started is a second payment.

## Agent

| Result | Action |
| - | - |
| `VOUCHER_ISSUED` | Sign and send `PAYMENT-SIGNATURE`. This is success, not an error. |
| `X402_AGENT_KEY_NOT_REGISTERED` | Register the workload key. Retry the same `orderRef` and the same payment idempotency key. |
| `AGENT_AUTHORIZATION_REQUIRED` | Finish the grant until it is `ACTIVE`. If a payment is in flight, retry the same order and key. |
| `POLICY_DECISION_DENIED` with `RISK_FIRST_TIME_MERCHANT` during a 402 | Retry the same order and key. Do not ask the borrower again. |
| Any other `POLICY_DECISION_DENIED` | Stop and show the code. |
| `X402_INTENT_EXPIRED` | Retry the same order and key. Do not request a new 402 challenge. |
| `PENDING` or `FAILED` from prepare | Stop. Do not sign. |
| Sanctions or AML decline | Stop. Do not open a new terminal to dodge it. See [AML screening](/compliance/aml-screening.md). |

Refresh the borrower token only when it is within about three minutes of expiry. Do not treat a missing scope on `whoami` as a signal to restart onboarding.

## Merchant

| Result | Action |
| - | - |
| Capture `200` | Store `receipt.paymentId` and poll. Do not fulfill yet. |
| Same `Idempotency-Key` and body | Expect `replayed: true` and the original receipt. |
| `X402_AGENT_VOUCHER_REQUIRED` | The client sent a V1 intent. Ask for a version-2 credit voucher. |
| Verify `isValid: false` | Do not capture. Surface `invalidReason`. |
| Poll `CREATED` or `SUBMITTED` | Keep polling. These are pending. |
| Poll `CONFIRMED` | Fulfill. |
| Poll `FAILED`, `TIMED_OUT`, or `DISPUTED` | Do not fulfill. See [Settlements](/guides/settlements-payouts.md). |
| HTTP 429 | Back off. Retry capture with the same idempotency key. See [Rate limits](/compliance/rate-limits.md). |

## Next steps

> [card] [Error codes](/api-reference/errors.md)
>
> The codes in one place.

> [card] [Payment flow](/guides/payment-flow.md)
>
> The happy path these branches leave.
