Errors - SohoPay

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. 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.

Identifiers in support requests

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

Next steps

Error handling

Which codes are safe to retry.

Facilitator reference

The merchant HTTP surface.