Payout errors
Every refusal a payout request can answer, and what to do about each.
Sandbox. The payout operations are in the API's contract and built for the sandbox, where a payout is simulated and never a real transfer. Until Nasfam switches payouts on in an environment, every request there answers 503 payouts_unavailable and nothing is written or held. Live: not yet available.
Availability: Sandbox. Built for the sandbox, on synthetic money. Not live.
A refusal is a problem document with a code, as every error of the API is, and param names the field where there is one. See Errors for its shape and the codes every request can meet.
Codes
| Code | When, and what to do |
|---|---|
| Invalid requestinvalid_ | A field is missing or malformed, or an amount has more decimal places than the pair. param names it. Fix the value. Do not retry as it is. |
| Unknown fieldunknown_ | The body carries a field the operation does not take. Remove the field. |
| Idempotency key requiredidempotency_ | A quote or a payout was sent with no Idempotency-Key. Send one key per new quote or payout. |
| Insufficient fundsinsufficient_ | Your available USD balance does not cover the total charge. Nothing is held. Fund your account, then quote again. |
| Insufficient scopeinsufficient_ | The key lacks the operation's scope: payouts:read to read, payouts:write to quote and send. Use a key with the scope the operation needs. |
| Not foundnot_ | The payout or quote is not your workspace's, or does not exist. Check the id. |
| Quote expiredquote_ | The quote passed its expires_at. Nothing is held. Ask for a new quote. |
| Quote already usedquote_ | A payout was already made from this quote. Ask for a new quote. |
| Quote mismatchquote_ | The body does not name what the quote priced. Send the quote's own asset, network, amount, address and memo. |
| Price changedprice_ | The total charge would be above max_total_charge. Nothing is made or held. Quote again, or raise the ceiling. |
| Duplicate referenceduplicate_ | Your client_reference was used before in this workspace. Use a new reference. |
| Idempotency in progressidempotency_ | A request with this key is still running. Wait, then send again with the same key. |
| Idempotency key reusedidempotency_ | The key was used with another body. A new payout needs a new key. |
| Network not supportednetwork_ | The pair is not one GET /v1/payout-networks lists here. Read GET /v1/payout-networks. |
| Destination not approveddestination_ | The address is not one of your workspace's approved, usable destinations for this asset and network. Approve it as a destination first. |
| Address invalidaddress_ | The address is not valid for this asset and network. Validate it, and ask your recipient again. |
| Memo requiredmemo_ | The destination needs a memo and none was sent. Ask your recipient for it. |
| Memo not allowedmemo_ | The network carries no memo. Send none. |
| Amount above maximumamount_ | Above what one payout may be priced at. Send less, in more than one payout. |
| Payout limit reachedpayout_ | A workspace or platform payout limit. detail names the window, never a figure. Wait for the window, or ask an Owner. |
| Payout blockedpayout_ | Your workspace's policy blocks this payout, or the key no longer stands for a member who may pay. Read your transaction policy, or use a current key. |
| Rate limitedrate_ | Past the payouts or reads request limit. Wait for Retry-After. |
| Internal errorinternal_ | Something failed on our side. On createPayout the outcome is unknown. Retry with the same Idempotency-Key: it never pays twice. |
| Payouts unavailablepayouts_ | Crypto payouts are not switched on in this environment. Nothing is written. Do not retry until payouts open here. |
| Pricing unavailablepricing_ | No fresh rate, network fee estimate or fee policy to price with. Nothing is held. Retry after Retry-After. |
| Service unavailableservice_ | The service is briefly unavailable. Nothing is held. Retry after Retry-After. |
Read the code, never the status alone: one status carries several codes.
No answer is not a refusal
A timeout, a dropped connection or a 5xx says nothing about the payout. Treat it as unknown: its charge may be held. Send the same request with the same key, or read the payout, before you tell anyone it failed.
Related guides
- Errors: the problem document and the codes every request can meet.
- Retrying a payout safely: sending again safely.
- Track a payout: reading a payout that may exist.
