> ## Documentation Index
> Fetch the complete documentation index at: https://docs.balaipedia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and limits

> HTTP status codes, error codes, rate limits and retry rules.

Errors use standard HTTP status codes and this body. Quote `request_id` when contacting support.

```json theme={null}
{"error":{"code":"insufficient_credit","message":"...","request_id":"req_..."}}
```

| HTTP | code | Meaning / what to do |
| - | - | - |
| 400 | `invalid_json`, `invalid_request` | Malformed JSON, a missing or wrongly typed field, or an invalid query value. Fix the request. Do not retry unchanged. |
| 401 | `unauthorized` | Missing or wrong API key. |
| 402 | `insufficient_credit` | Top up your balance. Response includes `balance`, `required` and `currency`. |
| 403 | `account_disabled`, `ip_not_allowed` | Contact support. |
| 404 | `not_found` | Unknown order, an order older than 60 days, or unknown URL. All endpoints live under `https://orders.balaipedia.com/v1`. |
| 405 | `method_not_allowed` | The URL exists but not for this HTTP method. The `Allow` header lists the valid methods. |
| 409 | `duplicate_order`, `request_in_progress` | Duplicate email (see `allow_duplicate`) or an order for it is still being processed; or the same Idempotency-Key is still running. Retry in a few seconds. |
| 413 | `payload_too_large` | Request body larger than 20 KB. |
| 422 | `email_rejected`, `idempotency_conflict` | Address failed validation (see `reason`), not charged; or the Idempotency-Key was reused with a different email. |
| 429 | `rate_limited`, `too_many_failed_attempts` | Wait for `Retry-After` seconds. Default limit: 60 requests/minute. Repeated wrong API keys from one IP are blocked for up to 15 minutes. |
| 500 | `internal_error` | Unexpected error. Retry later (with the same Idempotency-Key if you sent one). If it persists, contact support with the `request_id`. |
| 503 | `temporarily_unavailable`, `service_unavailable` | We could not process the request right now. Not charged. `temporarily_unavailable` always includes a `Retry-After: 30` header: wait that many seconds, then retry (with the same Idempotency-Key if you sent one). |

Optional extra fields on some errors: `reason`, `note` and `suggestion` (`422`), `balance`, `required` and `currency` (`402`).

## Failures by endpoint

All endpoints except `/ping` can return `401 unauthorized`, `403 account_disabled` or `ip_not_allowed`, `429` and `5xx`. Examples:

```text theme={null}
401  {"error":{"code":"unauthorized","message":"Missing or invalid API key.","request_id":"req_..."}}
403  {"error":{"code":"account_disabled","message":"This account is disabled. Please contact support.","request_id":"req_..."}}
403  {"error":{"code":"ip_not_allowed","message":"Requests from this IP address are not allowed.","request_id":"req_..."}}
429  {"error":{"code":"too_many_failed_attempts","message":"Too many failed authentication attempts. Try again later.","request_id":"req_..."}}
```

| Endpoint | Specific failures |
| - | - |
| `POST /orders` | See [Create order](https://docs.balaipedia.com/api-reference/create-order.md#other-failure-responses): `400`, `402`, `409`, `422`, `503`. |
| `GET /orders/{id}` | `404 not_found`: `{"error":{"code":"not_found","message":"Order not found. Orders older than 60 days are no longer available.","request_id":"req_..."}}`. Orders of other accounts are also reported as not found. |
| `GET /orders` | `400 invalid_request` for an unknown `status` filter (`Unknown "status" filter.`) or a bad `cursor` (`Invalid "cursor". Use the next_cursor value from the previous page.`). |
| `GET /balance` | Only the common failures above. |
| `GET /transactions` | `400 invalid_request` for a bad `cursor`. |
| `POST /webhook` | `400 invalid_request`: `"url" must be a public https URL on port 443 (no IP addresses).` |
| `POST /webhook/test` | `400 invalid_request`: `No webhook configured.` Set a webhook first. |
| `GET /webhook`, `POST /webhook/disable` | Only the common failures above. |
| Any URL | `404 not_found` (unknown path) or `405 method_not_allowed` (the `Allow` header lists valid methods). Unknown paths never return HTML. |

## Retries

* **Retry** on a network error or timeout, on `429` (wait `Retry-After`), on `409 request_in_progress`, and on any `5xx`. This includes a `5xx` whose body is not JSON (for example a gateway error page): in that case check only the HTTP status.
* If you sent an `Idempotency-Key` (recommended), **reuse the same key** and the same email when retrying `POST /orders`. You get the original order back and are never charged twice. Without a key we cannot tell a retry from a new request.
* Use a growing delay between attempts (for example 1s, 2s, 4s, up to a few minutes) and stop after a reasonable number of tries.
* **Do not retry unchanged** other `4xx` errors: fix the request first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.