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	amount exceeds your available balance.	Request ≤ your totalAvailable for that asset — check Get Balances.
409	conflict	Platform-billed gateways only — 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 → Platform-billed gateways.
422	invalid_asset	Unknown assetId.	Send an assetId for an asset enabled on your gateway.
422	validation_error	Bad amount or address (malformed, non-positive, below the network-fee floor, or invalid for the asset's chain).	Send a positive decimal-string amount above the fee floor and an address valid for the asset's chain.
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.