Error Codes and Troubleshooting

Common responses from payment and payout APIs and how to handle them:

• agent_auth_failed / agent_id_missing — Missing/invalid Authorization bearer JWT or no agent_id in claims. Ensure you send the registration JWT.
• missing_fields — Body is incomplete. Recheck scheme, network, amount, assetAddress, payTo, host, tokenName, tokenVersion.
• agent_not_found — External agent ID is unknown. Re‑authorize or recreate the agent.
• agent_not_authorized — Agent exists but is not user‑authorized. Open the provided authorizationUrl and complete authorization.
• no_signer / missing_wallet / missing_wallet_id — The agent’s wallet or session signer is missing. Re‑authorize and retry.
• need_approval — No matching policy; present approvalUrl for a one‑time approval or create a policy.
• approval_expired / approval_used — The approval link expired or was used. Re‑initiate approval and retry with the new approvalId.
• policy_denied — Request violates configured limits (per‑tx, daily amount/count, monthly). Adjust limits or wait for reset.
• risk_control_rejected — Rejected by risk control. Review recipient and amount; consider manual review or wait and retry.
• need_manual_signature — Risk control requires explicit user signature. Present approvalUrl to sign.
• wallet_api_not_configured / signing_failed — Server‑side signing unavailable or failed; contact wallet admin or re‑authorize and retry.

Tip: log and surface any payment_model_context.instructions included in responses to guide users.