Errors and retries

Error format

Errors are JSON with a machine-readable code, an HTTP status, a human-readable message, and sometimes structured data:

{
  "code": "INSUFFICIENT_BALANCE",
  "status": 422,
  "message": "Insufficient balance to approve this payout",
  "data": {
    "walletBalance": "50.00",
    "totalOpenAmount": "150.00",
    "currency": "EUR"
  }
}

Common codes

Retry guidance

• 4xx errors are yours to fix — retrying the identical request fails again (except 429).
• 5xx errors and network timeouts are safe to retry with exponential backoff. Payout creation is an upsert keyed on customId, so a retried create never duplicates a payout — see Idempotency.
• Write clients that ignore unknown fields: additive changes (new endpoints, new optional fields, new enum values) are not breaking and happen without notice. See Breaking changes.