Довідник помилок
Коди помилок BlockVectra, тарифікація та рекомендації щодо повторних спроб для JSON-RPC, Data API, Push Webhooks, консолі та крана, включно з діапазонами блоків eth_getLogs та помилками повтору Webhook.
Цей довідник документує всі коди помилок і машинозчитувані значення reason у сервісах BlockVectra, зокрема інформацію про те, чи тарифікується відхилений виклик, політики повторних спроб, тривалість відступу і рекомендовані дії для AI-агентів та автоматизованих клієнтів.
Для машинного використання завантажуйте повний каталог у форматі JSON за адресою /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?). |
| 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. |
| 429 | -32005 | public_pool_busy | Публічний пул мережі зайнятий | Ні | Так | Дотримуйтесь заголовка Retry-After або зачекайте кілька секунд і повторіть спробу із затримкою | Повторіть спробу із затримкою або надішліть запит з API key. Отримати API key. |
| 200 | -32601 | method_not_public | Метод недоступний на публічному ендпоінті | Ні | Ні | — | Використовуйте метод, який підтримується публічним ендпоінтом, або надішліть запит з API key. Отримати API key. |
| 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`); див. посібник із поповнення балансу для агентів, або скиньте ліміт у консолі, якщо маєте на це право. Якщо баланс відомий, 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`); див. посібник із поповнення балансу для агентів, скиньте ліміт, якщо це можливо, або дочекайтеся квоти наступного циклу. Якщо баланс відомий, 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`); див. посібник із поповнення балансу для агентів, або скиньте ліміт у консолі, якщо маєте на це право. |
| 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`); див. посібник із поповнення балансу для агентів, або дочекайтеся поповнення безкоштовної квоти. |
| 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`); див. посібник із поповнення балансу для агентів, або дочекайтеся наступного промо-циклу. |
| 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-доставки. Інтеграція отримувача починається з перевірки підпису вихідного тіла запиту; приклад платежів у стейблкоїнах додає дедуплікацію подій, перевірку квитанцій, заповнення прогалин і узгодження реорганізацій мережі. Див. правила білінгу щодо обліку та перепідключення до WebSocket для підписок на основі з'єднання.
Для logs_range_too_large перевірте параметри методу eth_getLogs і скористайтеся посібником з обмеження діапазону блоків та фрагментованих запитів.
Для запитів до крана у Robinhood Chain див. посібник із тестнет-крана щодо критеріїв доступності та обробки спільних кодів помилок.
Востаннє оновлено:
Версіонування та сумісність
Версіонування шляхів API BlockVectra, визначення зворотно сумісних змін, а також доступність мереж і методів.
Набори даних
Обирайте набори даних Blockchain Data API для балансів токенів, історії переказів, токенізованих акцій та інших індексованих даних. Перевірте покриття мереж, а потім відкрийте довідник запитів.