Error Codes and Troubleshooting

Payment and mandate endpoints return errors in this form:

{ "status": "error" | "denied", "code": "<machine_code>", "message": "...", "payment_model_context": { "instructions": "..." } }

Base your logic on code. When payment_model_context.instructions is present, show it to the model, because it says what to do next. Payment-link, payout and refund endpoints return { "error": "...", "code"?: "..." } instead. Linked-card endpoints return { "success": false, "error": { "code", "message" } }.

Authentication

• agent_auth_failed / agent_id_missing: The Authorization: Bearer JWT is missing, invalid or expired. Get a new JWT with /refresh.
• wrong_token_type: You sent an Agent VC to a wallet API. Wallet APIs need the login JWT. VCs are only for third-party services.
• agent_not_found / agent_not_authorized: The agent isn't linked to an authorized FluxA Wallet, or the user removed it. Open the returned authorizationUrl, or create a mandate to get one.
• need_approval: The user must approve before the payment can go ahead. Show approvalUrl (single payment) or authorizationUrl (link the agent), then retry. For V1, retry with the returned approvalId.

Request validation

• missing_fields: Required fields are missing. For USDC check scheme, network, amount, assetAddress, payTo, host, tokenName and tokenVersion.
• invalid_amount / invalid_pay_to / invalid_currency / unsupported_network / unsupported_currency: A field has an invalid or unsupported value.

Approvals (V1)

• approval_not_found / approval_mismatch: The approvalId is unknown or belongs to a different payment.
• approval_expired / approval_used: Call again without approvalId to start a new approval.
• user_denied: The user declined. Don't retry without asking them.

Mandates (V3, v2, payouts)

• mandate_required: Send a mandateId. The body may include intentOnboardUrl so the user can create one.
• mandate_not_found: The mandate doesn't exist or belongs to another agent.
• mandate_not_signed: The mandate is waiting for the user's signature. Show its signUrl.
• mandate_disabled: The user turned the mandate off.
• mandate_expired: The mandate is outside its validity window.
• mandate_inactive: The mandate can't be used for this payment (for example it was revoked, or the currency doesn't match).
• mandate_insufficient_budget: Not enough budget is left. Create a new mandate.
• agent_monthly_limit_exceeded: The agent's monthly limit, set by the user, would be exceeded.

Limits and risk

• policy_denied: The user's spending settings block this payment. Ask the user to review their limits; the response may include policyManagementUrl.
• risk_control_rejected: Blocked by risk checks. Don't retry automatically.
• need_manual_signature: The user has to sign this payment themselves. Show approvalUrl.
• insufficient_balance: The wallet doesn't have enough funds.

Payment links, UPL and refund links (public x402 endpoints)

• 202 with status: "processing": The payment was accepted and is still being confirmed. Don't pay again.
• payment_attempt_nonce_conflict: The nonce was already used. Sign again.
• hosted_checkout_required: The link is browser-only. Use checkoutUrl.

Temporary failures

Other codes, or any 5xx, mean FluxA couldn't complete the request right now. Retry with backoff. If the error keeps happening, ask the user to check the agent in FluxA Wallet (and re-link it if needed), or contact FluxA support with the time of the request.