Errors

Errors use standard HTTP status codes and a JSON body with a stable, machine-readable code.

{
  "error": {
    "code": "bad_request",
    "message": "amount must be > 0"
  }
}

Branch on error.code, not on the message: messages are for humans and may change.

General errors

HTTP	code	Meaning
400	`bad_request`	The request is malformed: invalid JSON, a missing field or a bad value. The message says which.
401	`unauthorized`	Authentication failed. See Authentication.
403	`merchant_inactive`	Your merchant account is not active.
404	`not_found`	Unknown route, unknown id, or the asset is not enabled for your account.
404	`chain_not_enabled`	The chain is not enabled for your account.
501	`not_implemented`	The chain is enabled but this operation is not available on it yet.
503	`chain_unavailable`	The chain is temporarily unavailable. Retry later.
503	`unavailable`	A dependency is temporarily unavailable. Retry with a new signature.
500	`internal`	Unexpected error on our side. Retry; contact us with the X-Request-Id if it persists.

Returned by POST /v1/payouts. No payout is created when one of these is returned.

HTTP	code	Meaning
400	`invalid_request`	A field is missing or invalid, for example a bad request_id.
400	`invalid_address`	The to address is not valid for the chain (bad checksum, wrong format or the zero address).
400	`internal_address`	The to address belongs to the gateway itself.
404	`asset_not_enabled`	The chain:token is not enabled for payouts on your account.
409	`vault_not_configured`	Your payout vault is not set up yet for this chain.
409	`request_id_conflict`	The request_id was already used with different parameters.
422	`below_minimum`	The amount is below the minimum payout.
422	`over_per_tx_limit`	The total (amount + fee) is over your per-transaction limit.
422	`over_daily_limit`	The total would exceed your daily limit (UTC day).
422	`insufficient_balance`	Your available balance does not cover the total.
423	`payouts_paused`	Payouts are paused for your account.