# Довідник помилок

> Source: https://docs.blockvectra.com/uk/errors/

Цей довідник документує всі коди помилок і машинозчитувані значення `reason` у сервісах BlockVectra, зокрема інформацію про те, чи тарифікується відхилений виклик, політики повторних спроб, тривалість відступу і рекомендовані дії для AI-агентів та автоматизованих клієнтів.

Для машинного використання завантажуйте повний каталог у форматі JSON за адресою [/errors.json](https://docs.blockvectra.com/errors.json). Кожна відповідь з помилкою, що містить `docs_url`, посилається безпосередньо на стабільний якір на цій сторінці: `https://docs.blockvectra.com/en/errors/#<reason>` (або `#-<code-number>` для помилок без коду причини).

### Помилки JSON-RPC



| HTTP | Код | Reason | Значення | Тарифікується | Можна повторити | Час очікування (Retry-After) | Дія агента |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | `Відсутній API key: передайте його в шляху запиту (/v1/{chain}/<api_key>) або в заголовку x-api-key` | Ні | Ні | — | Для ендпоінтів JSON-RPC (/v1/{chain}) передайте API key у шляху запиту (/v1/{chain}/<api_key>) або в заголовку x-api-key. Для Top-up API (/v1/topup/*) передавайте API key лише в заголовку x-api-key. |
| 401 | -32024 | `invalid_api_key` | `API key невідомий, вимкнений або відкликаний: JSON-RPC та Data API повертають HTTP 401 зі структурою відповіді про помилку invalid_api_key (JSON-RPC: error.code -32024 та error.data.reason invalid_api_key; Data API: error.code та error.data.reason invalid_api_key).` | Ні | Ні | — | Перевірте свій API key; якщо потрібно, увійдіть повторно в консоль або виконайте програмну реєстрацію, щоб створити новий ключ (див. [Втратили сесію або API key?](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)). |
| 403 | -32025 | `key_expired` | `Термін дії API key закінчився; створіть новий ключ у консолі` | Ні | Ні | — | Термін дії API key закінчився; створіть новий ключ у консолі або через програмну реєстрацію. |
| 403 | -32025 | `key_cap_exhausted` | `Загальний ліміт CU для API key вичерпано; створіть новий ключ у консолі` | Ні | Ні | — | Загальний ліміт CU для API key вичерпано; створіть новий ключ у консолі або через програмну реєстрацію. |
| 503 | -32021 | `auth_unavailable` | `Дані автентифікації тимчасово недоступні` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Сервер тимчасово не може перевірити ключі; це не проблема вашого ключа. Повторіть спробу після очікування відповідно до Retry-After; **не створюйте ключ заново**. |
| 404 | -32600 | `unknown_chain` | `Невідома мережа` | Ні | Ні | — | Перевірте доступні мережі через GET /v1/chains або інструмент list_chains; перевірте шлях URL. |
| 404 | 404 | `unknown_endpoint` | `Метод і шлях Data API не відповідають відомій операції` | Ні | Ні | — | Перевірте метод і шлях URL за документацією Data API. |
| 200 | -32700 | `parse_error` | `Помилка синтаксичного аналізу JSON` | Ні | Ні | — | Перевірте коректність синтаксису JSON у тілі запиту перед надсиланням. |
| 200 | -32600 | `invalid_request` | `Недійсний запит` | Ні | Ні | — | Перевірте структуру запиту; переконайтеся в наявності полів jsonrpc: '2.0', id та method перед повторним надсиланням. |
| 200 | -32602 | `invalid_params` | `Трейсер заборонено` | Ні | Ні | — | Скоригуйте параметри методу; перевірте підтримувані трейсери та ліміти таймаутів для мережі. |
| 200 | -32602 | `logs_range_too_large` | `Діапазон блоків eth_getLogs завеликий: максимум <N> блоків` | Ні | Ні | — | Звузьте діапазон блоків запиту до max_logs_block_range, зазначеного в GET /v1/chains. |
| 429 | -32005 | `public_rate_limit` | `Перевищено ліміт частоти загальнодоступних запитів` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Зачекайте відповідно до заголовка Retry-After і повторіть спробу; або надішліть запит з API key. [Отримати API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 429 | -32005 | `public_pool_busy` | `Публічний пул мережі зайнятий` | Ні | Так | Дотримуйтесь заголовка Retry-After або зачекайте кілька секунд і повторіть спробу із затримкою | Повторіть спробу із затримкою або надішліть запит з API key. [Отримати API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_public` | `Метод недоступний на публічному ендпоінті` | Ні | Ні | — | Використовуйте метод, який підтримується публічним ендпоінтом, або надішліть запит з API key. [Отримати API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_allowed` | `Метод недоступний у цій мережі або вимкнений політикою` | Ні | Ні | — | Перевірте methods.allow та methods.deny у GET /v1/chains щодо підтримуваних методів. Підтримка надсилання транзакцій визначається через methods.allow у GET /v1/chains. Надсилання транзакцій наразі недоступне на: HyperEVM. |
| 200 | -32601 | `subscription_not_available` | `Підписки WebSocket не надаються для цієї мережі` | Ні | Ні | — | Перевірте доступні підписки для цієї мережі через GET /v1/chains. |
| 200 | -32602 | `logs_filter_required` | `Підписка на logs вимагає вказати адресу або topic0 (ненульове значення на першій позиції topic)` | Ні | Ні | — | Вкажіть адресу або ненульовий topic0 у фільтрі логів. |
| 200 | -32600 | `batch_too_large` | `Пакет завеликий: максимум <N> викликів` | Ні | Ні | — | Розбийте пакет на менші частини, які відповідають максимальному ліміту викликів, зазначеному в даних помилки. |
| 413 | 413 | `request_too_large` | `Тіло запиту Data API перевищує ліміт розміру` | Ні | Ні | — | Зменшіть розмір тіла запиту. |
| 200 | -32000 | `not_found` | `Транзакцію не знайдено` | Ні | Ні | — | Якщо транзакція щойно надіслана або щойно видобута, зачекайте розповсюдження мережею та повторіть спробу; інакше перевірте номер блоку або хеш. |
| 200 | -32011 | `state_window` | `Історичний стан недоступний за межами останніх <N> блоків` | Ні | Ні | — | Запитуйте блоки в межах state_window_blocks, опублікованих у GET /v1/chains, або використовуйте Data API для історичних даних. |
| 200 | -32011 | `range_not_indexed` | `Запитану історію ще не повністю проіндексовано` | Ні | Ні | — | Звузьте запитану історію до діапазону, який уже проіндексовано; не повторюйте той самий запит для непокритого діапазону. |
| 200 | -32011 | `history_not_ready` | `Запитана історія ще не готова` | Ні | Так | Зачекайте, поки індексація наздожене дані; дотримуйтесь error.data.retry_after_seconds, якщо доступно | Повторіть спробу, коли індексація наздожене дані, зачекавши кількість секунд з error.data.retry_after_seconds, якщо вони вказані. |
| 429 | -32005 | `key_rate_limit` | `Перевищено ліміт швидкості CU для API key` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Зачекайте кількість секунд, зазначену в заголовку Retry-After, перед повторною спробою, або розподіліть навантаження. |
| 429 | rate_limited | `rate_limited` | `Перевищено ліміт частоти запитів до API або GET /v1/account (понад 5 запитів на секунду для цього ключа)` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Зачекайте інтервал, зазначений у Retry-After, перед повторною спробою. |
| 429 | -32005 | `concurrency_limit` | `Перевищено ліміт паралельних запитів` | Ні | Так | Дотримуйтесь заголовка Retry-After або зачекайте завершення активних викликів | Обмежте розмір пулу одночасних запитів клієнта та повторіть спробу, коли з'явиться вільне місце. |
| 429 | -32005 | `free_plan_call_limit` | `Перевищено ліміт викликів на секунду для безкоштовного плану` | Ні | Так | Зачекайте 1 секунду перед повторною спробою | Зменшіть частоту запитів або поповніть баланс, щоб відкрити платну пропускну здатність. |
| 429 | -32022 | `request_exceeds_burst` | `Вартість запиту <N> CU перевищує місткість сплеску <M> CU` | Ні | Ні | — | Очікування не допоможе; розділіть пакет або зменшіть параметри методу, щоб укластися в місткість сплеску. |
| 429 | -32022 | `free_plan_batch_too_large` | `Запит містить <N> викликів, що перевищує ліміт безкоштовного плану в <M> викликів на секунду` | Ні | Ні | — | Очікування не допоможе; розбийте пакет, щоб кількість викликів відповідала ліміту безкоштовного плану, або поповніть баланс. |
| 429 | -32005 | `ws_connection_limit` | `Досягнуто ліміту з'єднань WebSocket для цього ключа або облікового запису` | Ні | Ні | — | Закрийте невикористовувані з'єднання WebSocket або повторно використовуйте наявні з'єднання. |
| 200 | -32022 | `subscription_limit` | `Досягнуто ліміту підписок WebSocket для цього з'єднання` | Ні | Ні | — | Скасуйте підписку на події, які більше не потрібні, або відкрийте нове з'єднання WebSocket. |
| 200 | -32005 | `ws_filter_capacity` | `Фільтр логів WebSocket досяг максимальної місткості` | Ні | Ні | — | Скасуйте наявну підписку на логи або використовуйте вужчий фільтр. |
| 200 | -32026 | `ws_push_overloaded` | `Чергу push-сповіщень WebSocket перевантажено` | Ні | Так | Повторіть спробу пізніше із затримкою або перепідключіться | Повторіть eth_subscribe з експоненційною затримкою або перепідключіться. Наявні підписки продовжують отримувати сповіщення. |
| 200 | -32005 | `overloaded` | `Сервіс перевантажений, будь ласка, спробуйте пізніше` | Ні | Так | Зачекайте кілька секунд і повторіть спробу з експоненційною затримкою | Застосуйте затримку з джитером і повторіть запит. |
| 402 | -32020 | `balance_exhausted` | `Недостатньо коштів на балансі (якщо баланс відомий, error.data містить balance_units і balance_cu)` | Ні | Ні | — | Поповніть баланс ончейн: отримайте адресу для депозиту в консолі або через `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); див. [посібник із поповнення балансу для агентів](https://docs.blockvectra.com/en/guides/agent-topup/), або скиньте ліміт у консолі, якщо маєте на це право. Якщо баланс відомий, error.data містить balance_units (від'ємний у разі овердрафту) та balance_cu. |
| 402 | -32020 | `free_grant_exhausted` | `Безкоштовну квоту вичерпано (якщо баланс відомий, error.data містить balance_units і balance_cu)` | Ні | Ні | — | Поповніть баланс ончейн: отримайте адресу для депозиту в консолі або через `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); див. [посібник із поповнення балансу для агентів](https://docs.blockvectra.com/en/guides/agent-topup/), скиньте ліміт, якщо це можливо, або дочекайтеся квоти наступного циклу. Якщо баланс відомий, error.data містить balance_units (від'ємний у разі овердрафту) та balance_cu. |
| 503 | -32021 | `billing_unavailable` | `Дані тарифікації тимчасово недоступні` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Це не проблема з балансом; щойно створені ключі синхронізуються за кілька секунд. Зачекайте відповідно до Retry-After і повторіть спробу. |
| 200 | -32010 | `node_syncing` | `Вузол синхронізується; виклики тимчасово недоступні` | Ні | Так | Зачекайте кілька секунд і повторіть спробу | Зачекайте завершення синхронізації вузла або перевірте GET /v1/status. |
| 200 | -32603 | `upstream_unavailable` | `Апстрім-сервіс недоступний` | Ні | Так | Зачекайте кілька секунд і повторіть спробу | Повторіть спробу з експоненційною затримкою; перевірте GET /v1/status щодо справності вузла. |
| 504 | 504 | `upstream_timeout` | `Апстрім-сервіс не відповів протягом ліміту часу` | Ні | Так | Повторіть спробу після короткої затримки | Повторіть запит з експоненційною затримкою. |
| 200 | -32000 | `response_too_large` | `Відповідь апстріму занадто велика` | Ні | Ні | — | Звузьте параметри запиту (наприклад, зменшіть діапазон блоків в eth_getLogs або запитайте менший trace). |
| 200 | -32603 | `internal_error` | `Внутрішня помилка сервісу` | Ні | Ні | — | Повторіть запит; про тривалі збої повідомте службу підтримки із зазначенням мітки часу. |
| 200 | 4444 | — | `Усічена (pruned) історія недоступна` | Ні | Ні | — | Блок знаходиться за межами вікна збереженої історії усіченого вузла; запитуйте історичні блоки через Data API. |
| 200 | -32000 | — | `Історичний стан недоступний; старі дані недоступні через усічення` | Ні | Ні | — | Запитуйте блоки у вікні стану або використовуйте Data API для історичних запитів. |
| 200 | -32002 | — | `<node message>` | Ні | Так | Зачекайте кілька секунд і спробуйте знову з меншим пакетом | Зменшіть кількість викликів у пакеті та повторіть спробу. |
| 200 | -32003 | — | `<node message>` | Ні | Ні | — | Розбийте пакет на менші запити, щоб зменшити розмір відповіді. |
| 200 | -32601 | — | `<node message>` | Ні | Ні | — | Перевірте methods.allow та methods.deny у GET /v1/chains щодо підтримуваних методів. Підтримка надсилання транзакцій визначається через methods.allow у GET /v1/chains. Надсилання транзакцій наразі недоступне на: HyperEVM. |
| 200 | -32603 | — | `<node message>` | Ні | Так | Повторіть спробу після короткої затримки | Повторіть запит; про тривалі збої повідомте службу підтримки із зазначенням мітки часу. |
| 200 | -32600 | — | `<node message>` | Ні | Ні | — | Перевірте кожен запит у пакеті на невідповідні параметри; розділіть і повторіть спробу. |
| 200 | * | — | `<node message>` | Так | Ні | — | Вузол виконав обчислення, і виклик було тарифіковано. Перевірте причину/дані скасування (revert) або параметри виклику; не повторюйте спробу наосліп. |
| 408 | 408 | — | `Таймаут запиту через 35 секунд між завершенням заголовків запиту та відповіддю` | Можливо | Так | Зачекайте кілька секунд перед повторною спробою викликів читання | Виклик міг дійти до вузла й бути тарифікованим. Для викликів читання повторіть спробу із затримкою. Для викликів запису (наприклад, eth_sendRawTransaction) спочатку перевірте статус транзакції за хешем. |

### Коди закриття WebSocket

Коди закриття з'єднань WebSocket та рекомендовані дії для клієнта.

| Код | Reason | Значення | Можна повторити | Час очікування (Retry-After) | Дія агента |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | `Простій з'єднання (idle)` | Так | Перепідключіться за потреби | Перепідключіться за потреби. |
| 1003 | — | `Бінарні фрейми не підтримуються` | Ні | — | Не виконуйте автоматичне перепідключення; надсилайте лише текстові фрейми UTF-8. |
| 1009 | — | `Повідомлення завелике` | Ні | — | Не виконуйте автоматичне перепідключення; розбийте великі запити так, щоб вони не перевищували 1 МіБ. |
| 1012 | — | `Перезапуск сервісу` | Так | Перепідключіться із затримкою та джитером | Перепідключіться із затримкою та джитером, відновіть підписку та надолужте пропущені дані. |
| 1013 | — | `Мережа недоступна; перевантаження` | Так | Перепідключіться з експоненційною затримкою та повним джитером | Перепідключіться з експоненційною затримкою та повним джитером, відновіть підписку та надолужте пропущені дані. |
| 4402 | — | `Недостатній баланс` | Ні | — | Не виконуйте автоматичне перепідключення; поповніть баланс ончейн: отримайте адресу для депозиту в консолі або через `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); див. [посібник із поповнення балансу для агентів](https://docs.blockvectra.com/en/guides/agent-topup/), або скиньте ліміт у консолі, якщо маєте на це право. |
| 4404 | — | `Недійсний API key` | Ні | — | Не виконуйте автоматичне перепідключення; перевірте ключ або виконайте ротацію API key у консолі. |
| 4408 | — | `Сервіс закриває сесію, якщо черга push перевищує 512 КіБ (524,288 байтів), і скасовує незавершені сповіщення; клієнт може не отримати фрейм закриття (браузер повідомляє про 1006); обробляйте несподівані розриви з'єднання так само, як 4408.` | Так | Перепідключіться із затримкою; зменшіть кількість підписок або читайте швидше | Обробляйте несподівані розриви з'єднання без фрейму закриття (браузер повідомляє про 1006) як 4408: перепідключіться із затримкою, повторно встановіть підписки та надолужте втрачені дані за допомогою eth_getLogs; зменшіть кількість підписок або читайте швидше. |
| 4429 | — | `Перевищено швидкість push` | Так | Перепідключіться із затримкою або зменшіть кількість підписок | Зменшіть кількість підписок або перепідключіться із затримкою. |
| 4503 | — | `Сервіс тарифікації недоступний` | Так | Перепідключіться з експоненційною затримкою та повним джитером | Перепідключіться з експоненційною затримкою та повним джитером, потім підпишіться знову. |

### Помилки Data API

Помилки, які повертаються ендпоінтами Blockchain Data API у /v1/data/{chain}/.

| HTTP | Код | Reason | Значення | Тарифікується | Можна повторити | Час очікування (Retry-After) | Дія агента |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | `Дублювання параметрів запиту, недійсний рядок запиту або некоректно сформований запит` | Ні | Ні | — | Перевірте параметри запиту; переконайтеся, що такі параметри, як limit, зустрічаються щонайбільше один раз і всі параметри дійсні. |
| 409 | not_indexed_yet | — | `Запитаний номер блоку або вікно перевищує as_of_block, або визначений хеш перевищує as_of_block (містить indexed_through, якщо в мережі вже проіндексовано хоча б один блок)` | Ні | Так | Зачекайте кілька секунд, доки indexed_through не досягне запитаного блоку | Опитуйте, доки запитаний блок або to_block не стане меншим або рівним indexed_through, або зачекайте, поки мережа почне записувати блоки. |
| 409 | window_too_large | — | `Вікно блоків перевищує 100,000 блоків, а параметр clamp не встановлено в true` | Ні | Ні | — | Звузьте діапазон блоків (від from_block до to_block) до <= 100,000 блоків або передайте clamp=true. |
| 409 | too_many_pools | — | `Токен відповідає більш ніж 200 пулам ліквідності; виконайте запит за пулом` | Ні | Ні | — | Вкажіть конкретний пул для запиту замість загального запиту за токеном. |
| 409 | span_exceeded | — | `Запитаний інтервал дат перевищує максимальний ліміт у 90 днів` | Ні | Ні | — | Звузьте діапазон дат від from_time до to_time максимум до 90 днів. |
| 422 | no_coverage | — | `Функція не підтримується в цій мережі або запитаний блок передує вікну даних` | Ні | Ні | — | Перевірте `features` та `coverage.from_block` у GET /v1/data/chains (або `data_features` у безкоштовному GET /v1/status) перед виконанням запиту. |
| 503 | unavailable | — | `Сервіс Data API тимчасово недоступний` | Ні | Так | Зачекайте кілька секунд і повторіть спробу з експоненційною затримкою | Повторіть спробу після короткої паузи з експоненційною затримкою. |
| 402 | insufficient_balance | — | `Платний баланс або безкоштовна квота вичерпані (якщо баланс відомий, error.data містить balance_units і balance_cu)` | Ні | Ні | — | Поповніть баланс ончейн: отримайте адресу для депозиту в консолі або через `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); див. [посібник із поповнення балансу для агентів](https://docs.blockvectra.com/en/guides/agent-topup/), або дочекайтеся поповнення безкоштовної квоти. |
| 429 | cost_exceeds_burst | — | `Один запит коштує більше, ніж місткість сплеску (burst capacity) ключа` | Ні | Ні | — | Розбийте запит на менші частини; повторна спроба того самого запиту ніколи не буде успішною. |
| 503 | gateway_overloaded | — | `Пропускна здатність Data API тимчасово вичерпана` | Ні | Так | Повторіть спробу із затримкою (Retry-After: 1) | Зменшіть кількість одночасних запитів за всіма ключами та мережами цього облікового запису; зачекайте відповідно до Retry-After перед повторною спробою. error.data.reason має значення null. |

### Помилки Console, Account та Faucet API

Помилки, які повертаються ендпоінтами керування, надання ключів, автентифікації та крана у /v1/.

| HTTP | Код | Reason | Значення | Тарифікується | Можна повторити | Час очікування (Retry-After) | Дія агента |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 409 | topup_disabled | — | `Поповнення призупинено або наразі немає доступних мереж для поповнення; нові адреси призначити неможливо, але раніше призначені адреси залишаються закріпленими за обліковим записом` | Ні | Ні | — | Перевірте доступність поповнення через GET /v1/topup/status; повторіть спробу пізніше, коли поповнення буде увімкнено. |
| 503 | deposit_unavailable | — | `Тимчасово неможливо призначити адресу для депозиту; повторіть спробу відповідно до заголовка Retry-After` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) та використовуйте експоненційну затримку | Повторіть спробу відповідно до заголовка Retry-After з експоненційною затримкою. |
| 400 | invalid_request | `invalid_username` | `Недійсний формат імені користувача (має містити літери, цифри або підкреслення)` | Ні | Ні | — | Вкажіть дійсне ім'я користувача, яке відповідає вимогам щодо символів і довжини. |
| 400 | invalid_request | `expires_at` | `Час закінчення дії ключа не в майбутньому або перевищує максимально дозволений термін дії` | Ні | Ні | — | Встановіть expires_at як позначку часу RFC 3339 у майбутньому в межах дозволеного періоду (за замовчуванням 365 днів) або використовуйте expires_in_secs. |
| 400 | invalid_request | `cu_cap` | `Параметр cu_cap поза допустимими межами (має бути цілим числом від 1 до 9007199254740991)` | Ні | Ні | — | Встановіть cu_cap цілим числом від 1 до 9007199254740991 або пропустіть його для необмеженої кількості CU. |
| 400 | siwe_invalid | `expired` | `Повідомлення Sign-In with Ethereum (SIWE) застаріло або nonce уже використано` | Ні | Так | Негайно отримайте новий challenge і підпишіть його | Запитайте новий challenge через /v1/auth/siwe/challenge та підпишіть щойно видане повідомлення. |
| 400 | siwe_invalid | `chain_mismatch` | `chainId у повідомленні SIWE не збігається з налаштуваннями сервера` | Ні | Ні | — | Використовуйте chainId, повернутий /v1/auth/siwe/challenge, під час формування повідомлення SIWE. |
| 400 | siwe_invalid | `domain_mismatch` | `domain у повідомленні SIWE не збігається з хостом сервера` | Ні | Ні | — | Переконайтеся, що domain та uri збігаються з хостом сервера, повернутим у challenge. |
| 400 | siwe_invalid | `signature` | `Помилка криптографічної перевірки підпису SIWE` | Ні | Ні | — | Переконайтеся, що повідомлення підписано приватним ключем, який відповідає вказаній адресі. |
| 409 | key_limit_reached | `active_keys` | `Кількість активних (не відкликаних) API key досягла максимального ліміту облікового запису` | Ні | Ні | — | Відкличте наявний невикористовуваний ключ перед створенням нового. |
| 409 | no_reset_available | `nothing_to_reset` | `Баланс уже дорівнює цільовому значенню скидання або перевищує його; можливість скидання збережено` | Ні | Ні | — | Немає потреби скидати баланс, доки він не вичерпаний; використайте можливість, коли баланс закінчиться. |
| 429 | rate_limited | `daily_creations` | `Досягнуто ліміту створення ключів за 24 години для облікового запису` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Виконуйте ротацію наявних ключів замість створення нових або зачекайте завершення 24-годинного вікна. |
| 429 | signup_rate_limited | `per_ip` | `Досягнуто ліміту частоти реєстрації для IP-підмережі клієнта` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Зачекайте інтервал Retry-After перед створенням нових облікових записів із цієї мережі. |
| 429 | signup_rate_limited | `global` | `Досягнуто глобального ліміту частоти реєстрації нових користувачів з усіх джерел` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Зачекайте інтервал Retry-After перед повторною спробою створення облікового запису. |
| 400 | oauth_invalid | — | `Недійсні параметри OAuth або невідомий, прострочений чи вже використаний стан зворотного виклику` | Ні | Так | — | Розпочніть новий потік входу через OAuth із /v1/auth/{provider}/start. |
| 400 | login_code_invalid | — | `Код входу невідомий, прострочений, уже використаний або не відповідає верифікатору PKCE` | Ні | Ні | — | Почніть вхід спочатку, щоб отримати свіжий код входу. |
| 401 | unauthenticated | — | `Сесія відсутня, або токен сесії недійсний, прострочений чи відкликаний; у Top-up API (/v1/topup/*) ця помилка також виникає, якщо заголовок Authorization містить не Bearer або недійсний токен замість x-api-key` | Ні | Ні | — | Увійдіть повторно, щоб отримати новий токен сесії Bearer; для Top-up API передавайте API key у заголовку x-api-key замість Authorization. |
| 403 | user_disabled | — | `Обліковий запис призупинено адміністратором` | Ні | Ні | — | Зверніться до contact@blockvectra.com для підтримки облікового запису. |
| 404 | provider_disabled | — | `Провайдер OAuth розпізнаний, але наразі вимкнений` | Ні | Ні | — | Використовуйте SIWE або іншого підтримуваного провайдера автентифікації. |
| 409 | identity_in_use | — | `Ідентифікатор (гаманець або обліковий запис OAuth) уже прив'язаний до іншого користувача` | Ні | Ні | — | Відв'яжіть ідентифікатор від попереднього облікового запису або скористайтеся іншим. |
| 409 | identity_limit_reached | — | `Досягнуто максимальної кількості прив'язаних ідентифікаторів (5) для цього облікового запису` | Ні | Ні | — | Відв'яжіть старий ідентифікатор перед додаванням нового. |
| 409 | last_identity | — | `Неможливо відв'язати єдиний залишковий ідентифікатор від облікового запису` | Ні | Ні | — | Додайте новий ідентифікатор перед відв'язуванням поточного. |
| 409 | key_not_active | — | `Спроба виконати ротацію вимкненого, відкликаного або простроченого API key` | Ні | Ні | — | Створіть новий ключ або виконайте ротацію активного ключа. |
| 409 | no_reset_available | — | `Для цього облікового запису більше немає доступних скидань квоти` | Ні | Ні | — | Поповніть баланс ончейн: отримайте адресу для депозиту в консолі або через `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); див. [посібник із поповнення балансу для агентів](https://docs.blockvectra.com/en/guides/agent-topup/), або дочекайтеся наступного промо-циклу. |
| 413 | payload_too_large | — | `Тіло запиту перевищує ліміт розміру в 64 КіБ` | Ні | Ні | — | Зменшіть розмір корисного навантаження запиту до менш ніж 64 КіБ. |
| 503 | signup_paused | — | `Глобальну реєстрацію нових користувачів тимчасово призупинено; чинні облікові записи входять у звичайному режимі` | Ні | Так | Спробуйте пізніше | Реєстрацію нових користувачів призупинено; перевірте статус і спробуйте пізніше. |
| 503 | usage_unavailable | — | `Служба звітування про використання тимчасово недоступна` | Ні | Так | Зачекайте кілька секунд і спробуйте знову | Впливає лише на ендпоінт /usage; інші ендпоінти працюють у звичайному режимі. Повторіть спробу після короткої паузи. |
| 500 | internal | — | `Неочікувана внутрішня помилка сервера` | Ні | Так | Повторіть спробу після короткої затримки | Повторіть запит з експоненційною затримкою. |
| 400 | invalid_address | `invalid_address` | `Недійсний формат або контрольна сума (checksum) адреси одержувача` | Ні | Ні | — | Використовуйте 0x із 40 шістнадцятковими символами, у нижньому регістрі або з контрольною сумою EIP-55; перевірте data.field (/address). |
| 503 | faucet_empty | `faucet_empty` | `У крані недостатньо коштів для виплати запиту та покриття комісії за транзакцію` | Ні | Так | Дотримуйтесь заголовка Retry-After (секунди) | Зачекайте відповідно до Retry-After перед повторною спробою; не вважайте, що тестовий ETH надіслано, доки не отримано відповідь про успішне прийняття. |
| 503 | service_unavailable | `service_unavailable` | `Обробка запитів крана тимчасово недоступна, або попередня виплата ще не отримала квитанції (receipt) транзакції` | Ні | Так | Дотримуйтесь заголовка Retry-After | Зачекайте відповідно до Retry-After перед повторною спробою; не вважайте, що тестовий ETH надіслано, доки не отримано відповідь про успішне прийняття. |

### Помилки Push API

Помилки керування підписками webhook та історії подій у /v1/push/.

| HTTP | Код | Reason | Значення | Тарифікується | Можна повторити | Час очікування (Retry-After) | Дія агента |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | — | `Недійсні поля запиту, адреси, пагінація або діапазон блоків.` | Ні | Ні | — | Перевірте data.field та data.invalid; виправте запит. |
| 401 | missing_api_key | — | `Відсутній x-api-key.` | Ні | Ні | — | Надішліть API key у заголовку x-api-key. |
| 401 | invalid_api_key | — | `API key невідомий, вимкнений або відкликаний.` | Ні | Ні | — | Використовуйте активний ключ вашого облікового запису. |
| 402 | insufficient_balance | — | `Баланс або безкоштовний ліміт вичерпано для історії подій.` | Ні | Ні | — | Перевірте data.reason (balance_exhausted або free_grant_exhausted) і data.balance_units / data.balance_cu, якщо доступні; поповніть баланс через data.topup_url або data.deposit_address_url. |
| 403 | key_cap_exhausted | — | `Ліміт CU для API key вичерпано для історії подій.` | Ні | Ні | — | Перевірте data.cu_cap і створіть новий ключ у консолі. |
| 403 | key_expired | — | `Термін дії API key закінчився.` | Ні | Ні | — | Використовуйте ключ вашого облікового запису, термін дії якого не закінчився. |
| 404 | not_found | — | `Маршрут, метод або підписку на webhook не знайдено.` | Ні | Ні | — | Перевірте шлях, метод і обліковий запис, якому належить підписка. |
| 409 | limit_reached | — | `Досягнуто ліміту підписок або пар адрес для облікового запису.` | Ні | Ні | — | Перевірте data.limit та data.max; зменшіть кількість підписок або адрес. |
| 413 | request_too_large | — | `Тіло запиту перевищує ліміт маршруту.` | Ні | Ні | — | Зменшіть розмір списку адрес або розділіть його на пакети. |
| 422 | chain_not_available | — | `Мережа недоступна для push або не входить до підписки.` | Ні | Ні | — | Перевірте GET /v1/push/chains та мережі підписки. |
| 422 | chains_required | — | `Потрібна хоча б одна мережа.` | Ні | Ні | — | Вкажіть непорожній об'єкт chains; використовуйте статус offline, щоб припинити прослуховування. |
| 422 | confirmations_out_of_range | — | `Глибина підтверджень виходить за межі діапазону мережі.` | Ні | Ні | — | Виберіть confirmations у межах від data.min до data.max. |
| 422 | destination_not_allowed | — | `URL-адреса призначення webhook неприпустима.` | Ні | Ні | — | Перевірте data.rule; використовуйте ім'я хоста HTTPS на порту 443 без облікових даних користувача або фрагментів. |
| 422 | block_out_of_range | — | `Діапазон блоків виходить за межі допустимого відтворення або доступної історії.` | Ні | Ні | — | Використовуйте data.min_block та data.max_block для коригування діапазону. |
| 429 | cost_exceeds_burst | — | `Вартість запиту історії перевищує місткість сплеску (burst capacity) ключа.` | Ні | Ні | — | Перевірте data.reason (request_exceeds_burst) та data.max; збільште місткість сплеску перед повторною спробою. Повторення того самого запиту не допоможе. |
| 429 | rate_limited | — | `Досягнуто ліміту частоти запитів для керування або запитів історії.` | Ні | Так | Зачекайте відповідно до Retry-After | Для історії перевірте data.reason (key_rate_limit або free_plan_call_limit); зачекайте кількість секунд у Retry-After та зменшіть частоту або паралелізм запитів. |
| 500 | internal_error | — | `Неочікувана помилка сервісу.` | Ні | Ні | — | Збережіть x-bv-request-id і зверніться до служби підтримки. |
| 503 | auth_unavailable | — | `Автентифікація API key тимчасово недоступна.` | Ні | Так | Зачекайте кількість секунд у Retry-After. | Зачекайте кількість секунд у Retry-After перед повторною спробою. |
| 503 | billing_unavailable | — | `Статус тарифікації історії тимчасово недоступний.` | Ні | Так | Зачекайте кількість секунд у Retry-After. | Зачекайте кількість секунд у Retry-After перед повторною спробою. |
| 503 | upstream_unavailable | — | `Сервіс Push тимчасово недосяжний.` | Ні | Так | Зачекайте кількість секунд у Retry-After. | Зачекайте кількість секунд у Retry-After перед повторною спробою. |
| 503 | service_unavailable | — | `Сервіс Push або місткість адрес тимчасово недоступні.` | Ні | Так | Зачекайте кількість секунд у Retry-After. | Зачекайте кількість секунд у Retry-After перед повторною спробою. |

У разі помилок підписки на Webhook або повтору доставки дотримуйтесь [посібника з відновлення Push-доставки](https://docs.blockvectra.com/en/guides/webhook-push/#delivery-retries-and-replay). Інтеграція отримувача починається з [перевірки підпису вихідного тіла запиту](https://docs.blockvectra.com/en/guides/webhook-push/#verify-signatures); [приклад платежів у стейблкоїнах](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks) додає дедуплікацію подій, перевірку квитанцій, заповнення прогалин і узгодження реорганізацій мережі. Див. [правила білінгу](https://docs.blockvectra.com/en/guides/billing-rules/#webhook-push-billing) щодо обліку та [перепідключення до WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/#reconnection-and-exponential-backoff) для підписок на основі з'єднання.

Для `logs_range_too_large` перевірте [параметри методу eth\_getLogs](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/) і скористайтеся [посібником з обмеження діапазону блоків та фрагментованих запитів](https://docs.blockvectra.com/en/guides/getlogs-block-range/).

Для запитів до крана у Robinhood Chain див. [посібник із тестнет-крана](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/) щодо критеріїв доступності та обробки спільних кодів помилок.