Что не тарифицируется: коды ошибок и правила списания

BlockVectra измеряет потребление запросов в Compute Units (CU). Вызовы JSON-RPC и Data API тарифицируются только после получения ответа. В этом руководстве представлены правила тарификации для кодов состояния HTTP, вызовов JSON-RPC и Data API, а также рекомендации для разработчиков.

Коды состояния HTTP и правила тарификации

Правила определения тарификации и обработки ответов на уровне HTTP:

Примечание: при доступе через Cloudflare могут возвращаться страницы ошибок 52x или 1015; они генерируются не сервисом.

Заголовки ответа со списаниями и балансом: при передаче заголовка x-bv-meter: 1 в HTTP-запросах (применимо как к JSON-RPC, так и к Data API) ответ, в котором был списан хотя бы один вызов, возвращает x-bv-cu-charged (объем Compute Units, списанных за этот запрос, или сумму по тарифицируемым вызовам в пакете) и x-bv-balance-units (остаток расчетных единиц на балансе аккаунта сразу после этого списания; отрицательный при перерасходе; опускается, если баланс неизвестен). В запросах без x-bv-meter: 1, ответах без списаний, а также в ответах с ошибками 402, 403, 429 или 503 оба заголовка опускаются. Эти заголовки ответов доступны скриптам браузера через CORS, тогда как WebSocket их не использует. Из баланса вычитается общий объем еще не списанного использования, однократно округленный вверх до целых единиц; ежечасный расчет округляется вниз, поэтому отображаемый баланс после списания может увеличиться максимум на одну единицу.

Коды ошибок JSON-RPC и правила тарификации

Один и тот же код ошибки может исходить как от платформы, так и от узла, и тарификация различается:

• Ошибки, сгенерированные самой платформой: никогда не тарифицируются;
• Ошибки, возвращенные узлом: передаются без изменений и тарифицируются по весу метода, за исключением лишь перечисленных ниже кодов ошибок узла.

Детали правил

• Ошибки узла, которые не тарифицируются: ошибки узла -32002 (таймаут пакета), -32003 (слишком большой ответ на пакет) и -32600 (пакет отклонен целиком) указывают на то, что узел досрочно прервал обработку вызова; они и любые уведомления в том же пакете не тарифицируются. Ошибки узла -32601 (доступный метод не реализован) и -32603 (внутренний сбой узла) не тарифицируются по HTTP или WebSocket и не влияют на другие вызовы или уведомления в пакете. Кроме того, ошибки 4444 (удаленный/pruned блок) и -32000 (историческое состояние вне окна истории состояния узла, заданного параметром state_window_blocks в GET /v1/chains) не тарифицируются и не влияют на другие вызовы в пакете.
• Ошибки узла, которые тарифицируются: другие ошибки, возвращаемые узлом, тарифицируются по весу метода, когда они отражают результат выполнения в сети, например execution reverted (-32000 или 3 с data), собственная ошибка узла -32602 invalid argument.
• Допуск по балансу и синхронизация: код -32020 указывает на недостаточный баланс аккаунта и требует пополнения; когда баланс известен, поля error.data.balance_units и error.data.balance_cu содержат остаток (он может быть отрицательным). Вновь созданный ключ может в течение нескольких секунд возвращать -32021 (503); подождите время из Retry-After и повторите попытку.
• Сбои апстрима: ошибка -32603, сгенерированная платформой из-за сбоя связи с апстримом или некорректного ответа (upstream unavailable, no response from upstream, malformed upstream response), содержит data.reason: upstream_unavailable.
• Тарификация уведомлений: уведомления (204) тарифицируются по весам соответствующих методов.

Таблица кодов ошибок JSON-RPC

Правила тарификации Data API

Data API предоставляет данные блокчейна только для чтения через эндпоинты REST. Его тарификация и обработка ошибок подчиняются следующим правилам:

Детали правил

• Тарифицируются только успешные ответы 2xx.
• Недоступные операции за пределами зоны покрытия (например, неподдерживаемые сети или блоки вне зоны покрытия трассировки) возвращают HTTP 422 no_coverage, что не тарифицируется, но учитывается в лимитах скорости.
• Ответы HTTP 401, 402, 404 и 429 не тарифицируются. Описание заголовков ответа (x-bv-meter: 1) см. в разделе Коды состояния HTTP и правила тарификации.

Таблица кодов состояния Data API

Проверка баланса (GET /v1/account)

Владелец API key может проверять баланс и лимиты квот ключа напрямую, без тарификации и списания Compute Units (CU):

curl -H "x-api-key: $BLOCKVECTRA_API_KEY" https://api.blockvectra.com/v1/account

• Бесплатно и без списаний: запрос GET /v1/account бесплатен. Он никогда не тарифицируется, не списывает CU и возвращает HTTP 200 с текущим балансом, даже если он равен нулю или отрицателен (он никогда не возвращает 402).
• Аутентификация: аутентификация по ключу осуществляется исключительно через заголовок x-api-key (ключи в пути URL и токены Bearer не принимаются). Отсутствие заголовка возвращает 401 missing_api_key; недействительные или отозванные ключи возвращают 401 invalid_api_key. (Истекшие ключи возвращают 403 key_expired; временная недоступность сервиса возвращает 503 auth_unavailable или billing_unavailable с Retry-After.)
• Ограничение частоты: действует независимый лимит в 5 запросов в секунду на ID ключа, не зависящий от учета CU и биллинга. Превышение лимита возвращает HTTP 429 rate_limited с заголовком Retry-After.

Поля ответа:

• key_id: строка идентификатора API key.
• plan: тип плана аккаунта (free, если у аккаунта есть лимит частоты вызовов бесплатного плана; иначе paid).
• balance_units: оставшийся баланс аккаунта в расчетных единицах (может быть нулевым или отрицательным).
• balance_cu: оставшийся баланс, пересчитанный в Compute Units (CU).
• balance_as_of_age_ms: количество миллисекунд, прошедших с момента считывания баланса из источника данных.
• key: специфичные для ключа лимиты и сведения о квотах:
  • cu_per_sec: скорость пополнения токен-бакета в CU в секунду.
  • burst_cu: емкость всплеска токен-бакета в CU.
  • cu_cap: общий лимит CU за все время жизни для этого ключа или null, если лимит не установлен.
  • cu_cap_remaining: остаток CU в рамках cu_cap или null, если лимит не установлен (может быть нулевым или отрицательным).
  • expires_at: временная метка окончания срока действия в формате RFC 3339 или null, если ключ бессрочный.

Пример ответа:

{
  "key_id": "<key_id>",
  "plan": "<plan>",
  "balance_units": <integer>,
  "balance_cu": <integer>,
  "balance_as_of_age_ms": <integer>,
  "key": {
    "cu_per_sec": <integer>,
    "burst_cu": <integer>,
    "cu_cap": <integer_or_null>,
    "cu_cap_remaining": <integer_or_null>,
    "expires_at": "<expires_at_or_null>"
  }
}

Цены и повышение тарифа

Точная стоимость всех тарифицируемых вызовов определяется опубликованными весами в CU:

• Чтобы ознакомиться с весами всех методов и операций, см. таблицу весов методов и правила учета CU в JSON-RPC.
• Цены планов и детали списаний см. на странице Цены.
• Переход на платный тариф: платное пополнение снимает посекундное ограничение вызовов бесплатного плана; для каждого ключа продолжают действовать лимиты скорости CU и лимиты всплесков.

Процесс ончейн-пополнения

Когда баланса аккаунта недостаточно или вам требуется более высокая пропускная способность, выполните ончейн-пополнение в консоли, следуя этим шагам:

1. Войдите в консоль: выполните вход в консоль BlockVectra.
2. Перейдите на страницу биллинга: откройте страницу биллинга.
3. Получите выделенный адрес: в карточке ончейн-пополнения скопируйте выделенный адрес пополнения вашего аккаунта или отсканируйте QR-код.
4. Переведите средства: выполняйте перевод только в поддерживаемых сетях и в USDC / USDT / USDG, указанных на странице. Поддерживаемые сети и минимальные суммы пополнения отображаются в консоли.
5. Автоматическое зачисление: после обнаружения в сети транзакции отображаются в статусе "В обработке"; после подтверждения кредиты автоматически зачисляются на ваш баланс.

Важные примечания:

• Используйте только те сети и токены, которые явно указаны в консоли. Переводы в неподдерживаемых сетях или с неправильными токенами не могут быть зачислены автоматически.
• Убедитесь, что каждый перевод соответствует минимальной сумме пополнения, указанной в консоли.
• После зачисления первого платного пополнения ваш аккаунт переводится на платный тариф, что снимает посекундный лимит вызовов бесплатного плана.

Агенты или серверные программы могут напрямую вызывать эндпоинты пополнения с помощью API key; см. руководство по программному пополнению для агентов.

Тарификация Webhook push

Для Push действуют отдельные веса для доставленных событий данных, успешных запросов истории и тарифицируемых адресо-дней. Вызовы управления, кроме истории событий, неудачные попытки доставки, автоматические повторы и служебные события бесплатны. Каждое доставленное событие тарифицируется один раз; повторная отправка клиентом и канонические события, доставленные повторно после реорганизации блоков, являются новыми тарифицируемыми доставками. Плата за адреса рассчитывается по максимальному количеству адресов каждой подписки во время ее нахождения онлайн в течение суток UTC; бесплатная квота адресов аккаунта распределяется между подписками, причем более старые подписки используют ее первыми. Адрес, присутствующий в двух подписках, учитывается дважды; добавление сетей изменяет плату за события, но не за адреса.

См. руководство по Blockchain Webhook API по настройке, проверке подписей и восстановлению доставки. В руководстве по платежам в стейблкоинах рассматривается проверка квитанций и дозагрузка через опрос; подписки WebSocket используют собственный учет соединений и уведомлений. Ошибки запросов перечислены в справочнике ошибок. Приведенные ниже веса получены из GET /v1/plans.

Следующие шаги

• Изучите каталог наборов данных, чтобы увидеть все наборы данных, индексируемые BlockVectra.
• Ознакомьтесь с бесплатным тарифом и ценами, чтобы узнать, что включено в ваш аккаунт.
• Войдите в консоль, чтобы создать API key.