Errors

Validation failures list the offending fields in validation_errors. Every error carries the request_id to quote to support.

{
  "status": "error",
  "error": {
    "type": "validation_error",
    "code": "validation_error",
    "message": "One or more request parameters are invalid.",
    "next_step": "Fix the fields listed in validation_errors and retry the request.",
    "validation_errors": [
      { "field": "country", "message": "country must be a 2-letter ISO code, e.g. CM" },
      { "field": "amount", "message": "amount is required as a decimal string, e.g. \"5000\"" }
    ],
    "request_id": "c4a1f8e2-9d30-47b6-8e5f-1a2b3c4d5e6f"
  }
}

The catalog is closed: these are all the codes the API returns today. Retries with the same Idempotency-Key are always safe on 5xx responses.

Errors describe a request that was refused; reason codes describe how an accepted transaction turned out. Every non-success outcome of a collection, payout or refund carries a reason_code from this closed vocabulary, on the resource itself, in its event history and in webhooks. Handle each code you care about explicitly, and make the default branch of your status switch mean undetermined: keep polling GET /{id} or wait for the webhook. A status your code does not handle is never a failure and never a success.