validation_failed | 400, 422 | The request is malformed or a field is invalid. errors[] lists the paths. A missing or badly sized Idempotency-Key is a 400. | Fix the request. |
|---|
unauthenticated | 401 | No valid credentials, a stale webhook timestamp, or an unconfigured webhook secret. | Sign in again or check the API key. |
|---|
forbidden | 403 | Your role lacks the permission. Roles are checked fail-closed. API keys can never approve. | Ask a workspace admin for the right role. |
|---|
not_found | 404 | No such resource, or it belongs to another workspace (the two look the same on purpose). | Check the id and the workspace. |
|---|
conflict | 409 | The change collides with existing data or another request. | Reload and retry if still valid. |
|---|
idempotency_conflict | 422 | That Idempotency-Key was already used with a different request. | Use a new key for a new request; reuse the key only to retry the same one. |
|---|
rate_limited | 429 | Too many requests from your address. | Wait and retry. |
|---|
invalid_state | 409 | The action is not possible in the payout's current state; the message says why. | Read the state; do the allowed next action. |
|---|
policy_violation | 403, 409, 422 | The payout breaks the active policy (for example a limit or maker-checker rule). | Change the payout or ask for a policy change. |
|---|
invoice_invalid | 422 | The invoice cannot be decoded or its signature fails. | Ask the payee for a new invoice. |
|---|
invoice_expired | 409, 422 | The invoice has expired. | Ask for a fresh invoice. Expiry alone never proves a payment failed. |
|---|
network_mismatch | 409, 422 | The invoice is for a different network than the wallet or workspace. | Use an invoice from the right network. |
|---|
amount_mismatch | 422 | The amount differs from the invoice amount. | Correct the amount. |
|---|
destination_mismatch | 409, 422 | The invoice's node is not the payee's bound node key. | Verify the payee, then ask for a new invoice. |
|---|
approval_invalid | 401, 409, 422 | A signature or approval cannot be accepted. It is also how a missing or wrong authenticator code is reported, with mfa_required: true in the body. | Re-sign the exact payout, or enter a current authenticator code. |
|---|
approval_stale | 409 | The policy changed after approval. | Submit the payout again. |
|---|
approval_insufficient | 409 | Not enough valid approvals yet. | Wait for the remaining approvers. |
|---|
wallet_unavailable | 409, 422, 503 | The wallet cannot be reached or is not connected. | Check the wallet connection. If a send was in progress, the payout will say checking, not failed. |
|---|
wallet_insufficient_permissions | 409 | The wallet credential cannot do what is needed (for example it is read-only). | Connect a credential that can pay invoices and look up payments. |
|---|
mainnet_disabled | 409, 422 | Mainnet execution is switched off. | Use regtest. Mainnet is not available. |
|---|
entitlement_exceeded | 402 | Your plan's limit is reached or the feature is not in your plan. The body names entitlement, plan, limit and used. | Free up a resource or change plan in billing. |
|---|
mfa_required | — | Reserved in the contract. Today a missing authenticator code is reported as approval_invalid with mfa_required: true. | See approval_invalid. |
|---|
send_blocked_unresolved | 409 | A payment for this payout already exists or is unresolved. Sending again is refused. | Reconcile or wait. Never retry. |
|---|
internal | 500, 502 | Something went wrong on our side, or a billing provider call failed. Nothing changed unless the response says so. | Quote the request_id to support. |
|---|