Errors overview (programmatic API)
How failed requests are returned, common validation rules, and shared auth behaviour. Per-route examples are on each endpoint tab (OAuth, collect, disburse, status).
Error envelope (non-2xx)
Failed requests return JSON with at least:
statusCode— HTTP statuserror— short label (e.g.Bad Request,Unauthorized)message— human-readable string, or an array of strings for global validation failuresrequestId,path,timestamp— request correlation- Optional
clientIp— included on some 403 programmatic IP allowlist denials
Global behaviour
- Validation — Unknown or invalid JSON fields return 400. The
messagefield may be a string or a list of validation errors. - Rate limits — Too many requests return 429 Too Many Requests. Back off and retry.
- IP allowlist — Requests must come from an IP on your programmatic allowlist (dashboard, up to three entries). An empty allowlist returns 403.
Where per-route HTTP tables live
Token (collections) and Token (disbursements) — full OAuth status table for POST /v1/oauth/…/token. Collect — POST /v1/collect. Collection status — GET /v1/collect/transactions/:transactionId. Disburse — POST /v1/disburse. Disbursement status — GET /v1/disburse/transactions/:transactionId. Webhook delivery and retries: Webhooks (incoming).
Bearer routes (POST /v1/collect, POST /v1/disburse, transaction GETs)
| HTTP | Typical cause |
|---|---|
| 401 | Missing or invalid Bearer token (Authorization Bearer access token is required, Invalid or expired access token). Account not eligible (pending approval, KYC, disabled, suspended). |
| 403 | Wrong token scope for the endpoint, IP not on your allowlist, or API disbursements disabled (for POST /v1/disburse). |
| 429 | Rate limit exceeded. |