Basics

Errors

Errors use normal HTTP status codes and always return the same JSON shape:

403 Forbidden

{
    "ok": false,
    "error": {
        "code": "insufficient_scope",
        "message": "This key does not have the balance:read permission. Create a key with it in the dashboard.",
        "docs": "https://dev.adolfjon.uz/docs/errors#insufficient_scope",
        "required_scope": "balance:read"
    },
    "meta": {
        "request_id": "req_9d1f0a2b3c4e5f6a7b80"
    }
}

Branch on error.code, not on the message: messages may get clearer over time, codes never change within v1. Some errors add fields such as param, required_scope or retry_after.

Every response, success or error, carries meta.request_id and an X-Request-Id header. Include it when you contact support; it lets us find your exact request.

All codes

Code	HTTP	Meaning and what to do
`invalid_request`	400	A parameter is wrong. error.param names it.
`unauthorized`	401	No key, or the key is not valid.
`key_expired`	401	The key passed its 90-day expiry. Roll it or create a new one.
`key_revoked`	401	The key was revoked.
`account_blocked`	403	The account that owns the key cannot use the API.
`app_not_approved`	403	Live key used before the app was approved. Use a test key until then.
`app_rejected`	403	The app was not approved.
`app_suspended`	403	The app is suspended; all its keys stop working.
`insufficient_scope`	403	The key lacks the permission. error.required_scope names it.
`ip_not_allowed`	403	The key has an IP allowlist and this IP is not on it.
`not_found`	404	No such endpoint or object.
`method_not_allowed`	405	v1 is read-only: only GET works.
`rate_limited`	429	Over the per-minute limit. Wait error.retry_after seconds.
`daily_quota_exceeded`	429	Over the daily limit. It resets at 00:00 Tashkent time (UTC+5).
`server_error`	500	Our fault. Retry with backoff and send us the request_id if it repeats.
`api_disabled`	503	The API is turned off for maintenance. See the status page.
`api_unavailable`	503	The API is not available yet.

Retrying

4xx: do not retry the same request; fix it first. The only exception is 429: wait retry_after seconds.
5xx: retry with backoff (for example 1 s, 2 s, 4 s, up to 5 tries).