Skip to content

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

CodeWhen, and what to do
Invalid requestinvalid_request · 400A 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_field · 400The body carries a field the operation does not take. Remove the field.
Idempotency key requiredidempotency_key_required · 400A quote or a payout was sent with no Idempotency-Key. Send one key per new quote or payout.
Insufficient fundsinsufficient_funds · 402Your available USD balance does not cover the total charge. Nothing is held. Fund your account, then quote again.
Insufficient scopeinsufficient_scope · 403The 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_found · 404The payout or quote is not your workspace's, or does not exist. Check the id.
Quote expiredquote_expired · 409The quote passed its expires_at. Nothing is held. Ask for a new quote.
Quote already usedquote_already_used · 409A payout was already made from this quote. Ask for a new quote.
Quote mismatchquote_mismatch · 409The body does not name what the quote priced. Send the quote's own asset, network, amount, address and memo.
Price changedprice_changed · 409The total charge would be above max_total_charge. Nothing is made or held. Quote again, or raise the ceiling.
Duplicate referenceduplicate_reference · 409Your client_reference was used before in this workspace. Use a new reference.
Idempotency in progressidempotency_in_progress · 409A request with this key is still running. Wait, then send again with the same key.
Idempotency key reusedidempotency_key_reused · 422The key was used with another body. A new payout needs a new key.
Network not supportednetwork_not_supported · 422The pair is not one GET /v1/payout-networks lists here. Read GET /v1/payout-networks.
Destination not approveddestination_not_approved · 422The address is not one of your workspace's approved, usable destinations for this asset and network. Approve it as a destination first.
Address invalidaddress_invalid · 422The address is not valid for this asset and network. Validate it, and ask your recipient again.
Memo requiredmemo_required · 422The destination needs a memo and none was sent. Ask your recipient for it.
Memo not allowedmemo_not_allowed · 422The network carries no memo. Send none.
Amount above maximumamount_above_maximum · 422Above what one payout may be priced at. Send less, in more than one payout.
Payout limit reachedpayout_limit_reached · 422A workspace or platform payout limit. detail names the window, never a figure. Wait for the window, or ask an Owner.
Payout blockedpayout_blocked · 422Your 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_limited · 429Past the payouts or reads request limit. Wait for Retry-After.
Internal errorinternal_error · 500Something failed on our side. On createPayout the outcome is unknown. Retry with the same Idempotency-Key: it never pays twice.
Payouts unavailablepayouts_unavailable · 503Crypto payouts are not switched on in this environment. Nothing is written. Do not retry until payouts open here.
Pricing unavailablepricing_unavailable · 503No fresh rate, network fee estimate or fee policy to price with. Nothing is held. Retry after Retry-After.
Service unavailableservice_unavailable · 503The 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.