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

# Errors

> Status and error codes an agent or merchant will see on the current payment path.

Agents see these codes on MCP tool results. Merchants see them on facilitator HTTP responses. The two surfaces do not share one error envelope. Branch on the code, not on a guessed HTTP status from an older guide.

## Agent and prepare

| Code | Meaning |
| - | - |
| `VOUCHER_ISSUED` | Prepare allowed the spend. Sign the unsigned voucher. |
| `X402_AGENT_KEY_NOT_REGISTERED` | This terminal has no Ed25519 workload key yet. |
| `AGENT_AUTHORIZATION_REQUIRED` | The agent grant is missing or not `ACTIVE`. |
| `POLICY_DECISION_DENIED` | Policy, risk, credit, or compliance refused the spend. Read the nested reason. |
| `RISK_FIRST_TIME_MERCHANT` | Reason on a denial: this merchant is new to the borrower. On a 402, retry the same order. |
| `X402_INTENT_EXPIRED` | The prepared intent expired. Retry the same order and the same idempotency key. |
| `X402_AGENT_VOUCHER_REQUIRED` | A V1 payment intent was submitted where a version-2 voucher is required. |

`PENDING` and `FAILED` from prepare are terminal for that attempt. Do not invent a signature.

## Merchant poll

`CREATED` and `SUBMITTED` are not errors. `FAILED`, `TIMED_OUT`, and `DISPUTED` mean do not fulfill. Definitions are on [Settlements](/guides/settlements-payouts.md).

Verify returns `isValid: false` with `invalidReason` when the envelope should not be captured. Capture returns HTTP 429 when the merchant is over the [rate limit](/compliance/rate-limits.md).

## Identifiers in support requests

Send `support@sohopay.ai` the staging environment, the borrower UUID or `paymentId`, and the code. Do not send workload private keys or borrower seeds.

## Next steps

> [card] [Error handling](/guides/error-handling.md)
>
> Which codes are safe to retry.

> [card] [Facilitator reference](/api-reference/introduction.md)
>
> The merchant HTTP surface.
