Errors and limits

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

{"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:

{"error":{"code":"unauthorized","message":"Missing or invalid API key.","request_id":"req_..."}}
{"error":{"code":"account_disabled","message":"This account is disabled. Please contact support.","request_id":"req_..."}}
{"error":{"code":"ip_not_allowed","message":"Requests from this IP address are not allowed.","request_id":"req_..."}}
{"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: `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.

Getting Started

Guides

Orders

Account

Webhook endpoints

Utility

Telegram bot

Failures by endpoint

Retries