Errors

Every non-2xx response uses the same JSON envelope:

{
  "ok": false,
  "error": {
    "code": "AccountNotFound",
    "message": "No account found for id acc_1a2b"
  },
  "request_id": "req_3f2a9c0d1b7e4f6a8c5d2e1b0a9f8e7d"
}

• ok: literal false, present only on errors. Success responses are flat payloads (e.g. { "id": "f01e…", "status": "awaiting_funds", … }) with no ok field. Callers that want body-level dispatch can check body.ok === false. HTTP status is still authoritative. This mirrors the semantics of fetch's Response.ok.
• code: stable PascalCase enum value. Safe to switch on programmatically. Will not change across minor releases. New codes may be added. Treat unknown codes as a generic failure at that HTTP status.
• message: human-readable detail with caller context. Surface to end users.
• request_id: reference for this request. Every response, success or error, also returns it as the x-request-id header. Quote it when contacting support.

Status codes

The HTTP status categorises. The code field identifies.

Error codes

Codes group by surface. Not exhaustive: the server may add codes. Unknown codes should be handled as a generic failure at their HTTP status.

Orgs + KYB

Auth

Note: LoginResponse separately reports status: "mfa_required" (not an error) when login succeeds but a TOTP challenge is still pending. That's the normal MFA-on-login flow, not the MfaRequired error code listed under Generic.

API keys

Customers + accounts

Quotes

Generic

Validation violations

When an InvalidRequest failure can be pinned to specific fields, the error body carries a violations array alongside message. Render the entries inline next to the offending inputs instead of parsing message.

{
  "ok": false,
  "error": {
    "code": "InvalidRequest",
    "message": "2 fields need attention",
    "violations": [
      {
        "field": "account_holder.address.line1",
        "reason": "missing",
        "description": "should not be empty"
      },
      {
        "field": "business_type",
        "reason": "not_in_allowed_set",
        "description": "must be one of the supported values",
        "allowed": [
          "b_corporation",
          "c_corporation",
          "limited_liability_company"
        ]
      }
    ]
  }
}

• field: dotted path into the request body you sent, with zero-based array indices (associated_persons.0.role). Omitted when the failure isn't tied to a single field.
• reason: stable snake_case slug, safe to switch on: missing, invalid_format, too_short, too_long, not_in_allowed_set, unknown_field, out_of_range, other. New slugs may be added. Treat unknown slugs like other.
• description: human-readable constraint detail. English-only. Suitable for developer tooling and logs.
• allowed: accepted values for field, present when reason is not_in_allowed_set. Omitted for very large value sets (e.g. the industry catalog). Consult the field's API reference instead.

Not every InvalidRequest carries violations. Treat the array as an optional enrichment, with code + message as the baseline contract.

Retry guidance

Handling specific cases

A few codes are worth dispatching on rather than treating as a generic failure:

• QuoteExpired: re-create the snapshot, show the new price, let the user re-confirm.
• AlreadyAccepted, treat as success: a prior request won the race.
• QuoteIdInvalid: UI sent an id that isn't in the snapshot. Log + report.
• CustomerNotVerified vs CustomerOnHold, both on account creation: the first means verification hasn't finished (retry when it does), the second means a verdict went against the customer (don't retry — status says whether the hold is clearable).
• VirtualAccountNotApproved, on virtual bank account creation: the customer is verified, but not for this currency. Retrying won't help — this clearance is granted per currency, on its own timeline. Read GET /v0/customers/{id}/virtual-account-approvals to see which currencies are open to them today, and offer one of those instead.
• InvalidRequest with a files + missing violation, on accept only: the destination corridor requires a compliance attachment (an invoice or similar payment-purpose document). Collect one and retry the accept with files populated. See Document required.