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

# Troubleshooting

> What to check when prepare, capture, or the status poll does not do what you expected.

## The agent cannot prepare a payment

* Confirm the host is `https://staging.mcp.sohopay.ai/mcp` (staging) or `https://mcp.sohopay.ai/mcp` (production, if you are cut over).
* `X402_AGENT_KEY_NOT_REGISTERED`: generate a workload key and call `register_agent_workload_key`, then retry the same order and idempotency key.
* `AGENT_AUTHORIZATION_REQUIRED`: open the grant `consent_url` and wait until `get_agent_authorization` is `ACTIVE`.
* The borrower has no handle: finish `claim_handle` before treating onboarding as done.
* Token near expiry: call `request_borrower_token`. Do not use `whoami` scopes as the refresh signal.

## Capture fails

* `x402Version` must be `2`. A V1 intent returns `X402_AGENT_VOUCHER_REQUIRED`.
* The bearer token must be a merchant JWT or an `sk_live_` key for that merchant. There is no `sk_test_` key, and `api-sandbox.sohopay.xyz` is not the API.
* HTTP 429: you are over 30 captures per minute. Retry with the same `Idempotency-Key`.

## The poll never reaches CONFIRMED

* `CREATED` for about a minute is the flush interval, not a failure.
* `SUBMITTED` means the batch is on chain and still gaining confirmations.
* `FAILED`, `TIMED_OUT`, or `DISPUTED`: do not fulfill. Check the merchant is `ACTIVE` in the registry, then contact support with the `paymentId`.
* Production will not settle. Protocol V2 is disabled there.

## Credit looks unchanged

Available credit moves when the batch entry is `CONFIRMED`, not when the voucher is signed. Read `get_outstanding_balance` after that status.

## Next steps

> [card] [Error handling](/guides/error-handling.md)
>
> The retry table.

> [card] [Testing](/guides/testing.md)
>
> A known-good staging loop.
