Errors & limits

Consistent JSON errors with machine-readable codes.

Errors use conventional HTTP status codes and a JSON body:

{
  "error": {
    "code": "validation_failed",
    "message": "The amount field is required.",
    "fields": { "amount": ["The amount field is required."] }
  }
}

HTTP	code	Meaning
401	`unauthenticated`	Missing or unknown `X-Zyvo-Key`.
401	`invalid_signature`	Signature does not match the raw body.
403	`merchant_frozen`	Your account is frozen — contact support.
404	`not_found`	Unknown invoice or withdrawal.
422	`validation_failed`	Invalid parameters; see `fields`.
422	`insufficient_balance`	Withdrawal exceeds your available balance.
422	`address_not_whitelisted` / `address_cooldown`	Payout address not whitelisted or still in its security cooldown.
422 / 503	`network_unavailable`	The network is disabled or temporarily out of deposit capacity.
429	`rate_limited`	More than 240 requests per minute per key.

← Quickstart Create invoice →