# 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 status
- `error` — short label (e.g. `Bad Request`, `Unauthorized`)
- `message` — human-readable string, or an array of strings for global validation failures
- `requestId`, `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 `message` field 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)](https://docs.swarmbyte.com/oauth-collections-token.md) and [Token (disbursements)](https://docs.swarmbyte.com/oauth-disbursements-token.md) — full OAuth status table for `POST /v1/oauth/…/token`. [Collect](https://docs.swarmbyte.com/collect.md) — `POST /v1/collect`. [Collection status](https://docs.swarmbyte.com/collect-status.md) — `GET /v1/collect/transactions/:transactionId`. [Disburse](https://docs.swarmbyte.com/disburse.md) — `POST /v1/disburse`. [Disbursement status](https://docs.swarmbyte.com/disburse-status.md) — `GET /v1/disburse/transactions/:transactionId`. Webhook delivery and retries: [Webhooks (incoming)](https://docs.swarmbyte.com/webhooks.md).

## 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. |

Source: https://docs.swarmbyte.com/errors-overview