Cashout Errors

Every cashout endpoint returns the standard error envelope ({ success: false, error: { code, message } }). Branch on error.code, never on message.

HTTP status	Error code	Meaning	How to fix
403	cashout_disabled	The cashout API is not enabled for this gateway.	Ask Finomesh to enable it for your gateway.
403	cashout_unavailable	Cashout is not available for this gateway at all (not provisioned).	Contact Finomesh — cashout must be provisioned before it can be enabled.
403	cashout_secret_missing	No cashout signing secret is configured for this gateway.	Generate the signing secret when you enable the API; if it is already enabled, contact Finomesh.
403	ip_not_allowlisted	Your source IP is not on the gateway's allowlist.	Add your server's public IP/CIDR under Server IP allowlist — API access. The message echoes the IP we actually observed — whitelist that one.
401	signature_required	Missing X-Timestamp / X-Signature.	Send both signing headers on every request.
401	signature_stale	Timestamp outside the 5-minute window.	Use current Unix time in seconds; keep your server clock NTP-synced.
401	signature_invalid	Signature did not verify (wrong secret, changed body, or X-Timestamp not valid Unix seconds).	Recompute HMAC_SHA256(secret, ts + "." + rawBody) over the exact raw bytes you send; confirm the secret and that X-Timestamp is integer seconds.
400	idempotency_key_required	Missing Idempotency-Key on create.	Send a unique Idempotency-Key header on POST /merchant/settlements.
409	idempotency_conflict	Same Idempotency-Key reused with a different body.	Use a new key for a new settlement, or resend the identical body to retry the original.
409	conflict	A state conflict rather than a bad request: the cashout no longer covers its own network fee, another cashout claimed the same funds first, or the settlement is no longer in the state the call needs (already approved, activated, cancelled, or expired). The message says which.	Re-read the settlement with Get Settlement Status and act on its current status. Nothing was changed.
409	insufficient_balance	amount exceeds the available balance of the pool you routed to. The message names both figures.	Request ≤ the pool's figure — totalAvailable, or totalQuarantinedAvailable for route: "AML_HELD" — from Get Balances. Or ask Finomesh to enable parking for your gateway, which turns this into a 202 parked cashout instead.
409	too_many_parked_cashouts	This gateway already holds the maximum number of parked cashouts. The message says how many.	Fund one (or cancel one) before requesting another.
409	screening_required	route: "SMART" but no destination verdict is available — AML screening is not enabled on this gateway, or the provider is unreachable.	Name the pool explicitly (GREEN or AML_HELD), or ask Finomesh to enable AML screening. Never assume a pool on our behalf.
422	below_minimum_settlement	The requested amount is below the settlement minimum in USD, so the cashout could never complete.	Request at or above the minimum named in the message. Returned instead of parking a request that would only fail later.
422	amount_below_network_fee	The requested amount does not cover its own network fee.	Withdraw a larger amount, or estimate the fee first.
409	conflict	Monthly-billed gateways only (platform-billed, or a standard gateway on monthly fee billing) — you have an overdue Finomesh invoice, or your outstanding balance with us exceeds your agreed limit. The message names the amount and the limit.	Pay the outstanding invoice; settlements resume as soon as it clears. Accepting payments is never blocked by this. See Settlement / Cashout → Monthly-billed gateways.
422	invalid_asset	Unknown assetId.	Send an assetId for an asset enabled on your gateway.
422	validation_error	Bad amount, address, or route — amount missing/malformed/non-positive, an address invalid for the asset's chain, or a route outside GREEN / AML_HELD / SMART.	Send a positive decimal-string amount, an address valid for the asset's chain, and either a valid route or none at all.
503	cashout_not_configured	The cashout endpoint is temporarily unavailable on our side.	Transient — retry with backoff; if it persists, contact Finomesh.
503	fee_estimation_unavailable	The chain fee estimate (used by estimate-fee and at create time) was momentarily unreachable.	Transient — retry shortly. Nothing was created.