# Справочник ошибок

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

В этом справочнике описаны все коды ошибок и машиночитаемые значения `reason` во всех сервисах BlockVectra, включая информацию о том, тарифицируется ли отклоненный вызов, политики повторных попыток, время ожидания (backoff) и рекомендуемые действия для ИИ-агентов и автоматизированных клиентов.

Для машиночитаемого использования скачайте полный каталог в формате 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` | `Подписка на логи требует указания адреса или topic0 (ненулевое значение в первой позиции topics)` | Нет | Нет | — | Укажите адрес или ненулевой 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 превышает емкость всплеска (burst) <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` | `Очередь уведомлений WebSocket перегружена` | Нет | Да | Повторите попытку позже с задержкой либо переподключитесь | Повторите вызов eth_subscribe с экспоненциальной задержкой либо переподключитесь. Существующие подписки продолжат получать уведомления. |
| 200 | -32005 | `overloaded` | `Сервис перегружен, повторите попытку позже` | Нет | Да | Подождите несколько секунд и повторите попытку с экспоненциальной задержкой | Примените задержку с джиттером и повторите запрос. |
| 402 | -32020 | `balance_exhausted` | `Недостаточно средств (когда баланс известен, error.data содержит balance_units и balance_cu)` | Нет | Нет | — | Пополните баланс on-chain: получите адрес депозита в консоли или через `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 và balance_cu)` | Нет | Нет | — | Пополните баланс on-chain: получите адрес депозита в консоли или через `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 MiB. |
| 1012 | — | `Перезапуск сервиса` | Да | Переподключитесь с задержкой и джиттером | Переподключитесь с задержкой и джиттером, оформите подписку заново и восполните пропущенные данные. |
| 1013 | — | `Сеть недоступна; перегрузка` | Да | Переподключитесь с экспоненциальной задержкой и полным джиттером | Переподключитесь с экспоненциальной задержкой и полным джиттером, оформите подписку заново и восполните пропущенные данные. |
| 4402 | — | `Недостаточно средств` | Нет | — | Не переподключайтесь автоматически; пополните баланс on-chain: получите адрес депозита в консоли или через `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 KiB (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 | — | `Сервис данных временно недоступен` | Нет | Да | Подождите несколько секунд и повторите попытку с экспоненциальной задержкой | Повторите попытку через небольшую паузу с экспоненциальной задержкой. |
| 402 | insufficient_balance | — | `Платный баланс или бесплатная квота исчерпаны (когда баланс известен, error.data содержит balance_units и balance_cu)` | Нет | Нет | — | Пополните баланс on-chain: получите адрес депозита в консоли или через `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 либо состояние callback неизвестно, истекло или уже использовано` | Нет | Да | — | Начните процесс входа 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 | — | `У этого аккаунта не осталось возможностей сброса квоты` | Нет | Нет | — | Пополните баланс on-chain: получите адрес депозита в консоли или через `GET /v1/topup/deposit-address` (MCP-инструмент `get_deposit_address`); см. [руководство по пополнению для агентов](https://docs.blockvectra.com/en/guides/agent-topup/) или дождитесь следующего промо-цикла. |
| 413 | payload_too_large | — | `Тело запроса превышает ограничение размера в 64 KiB` | Нет | Нет | — | Уменьшите размер тела запроса до значения менее 64 KiB. |
| 503 | signup_paused | — | `Регистрация новых пользователей временно приостановлена; вход для существующих пользователей работает штатно` | Нет | Да | Повторите попытку регистрации позже | Регистрация новых пользователей временно приостановлена; проверьте статус и повторите попытку позже. |
| 503 | usage_unavailable | — | `Сервис статистики использования временно недоступен` | Нет | Да | Подождите несколько секунд и повторите попытку | Влияет только на эндпоинт /usage; остальные эндпоинты работают в штатном режиме. Повторите попытку чуть позже. |
| 500 | internal | — | `Непредвиденная ошибка сервера` | Нет | Да | Повторите попытку после небольшой задержки | Повторите запрос с экспоненциальной задержкой. |
| 400 | invalid_address | `invalid_address` | `Формат или контрольная сумма адреса получателя недействительны` | Нет | Нет | — | Используйте 0x и 40 шестнадцатеричных символов, в нижнем регистре или с контрольной суммой EIP-55; проверьте data.field (/address). |
| 503 | faucet_empty | `faucet_empty` | `На балансе крана недостаточно средств для выплаты запрошенной суммы и комиссии за транзакцию` | Нет | Да | Следуйте заголовку Retry-After (в секундах) | Подождите время из Retry-After перед повторной попыткой; не предполагайте, что тестовый ETH отправлен, пока не получен ответ о принятии. |
| 503 | service_unavailable | `service_unavailable` | `Обработка запросов крана временно недоступна либо по предыдущему запросу еще не получен чек транзакции` | Нет | Да | Следуйте заголовку 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 | — | `Маршрут, метод или подписка не найдены.` | Нет | Нет | — | Проверьте путь, метод и принадлежность подписки аккаунту. |
| 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 | — | `Глубина подтверждений выходит за пределы диапазона сети.` | Нет | Нет | — | Выберите число подтверждений в диапазоне от 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-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 количество секунд перед повторной попыткой. |

При ошибках подписки на вебхуки или повторной отправки (replay) следуйте [руководству по восстановлению доставки 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) включает дедупликацию событий, проверку квитанций, восполнение пропусков и согласование при реорганизациях цепи (reorgs). Правила учета см. в [правилах тарификации](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/), где описаны критерии доступа и обработка общих кодов ошибок.