Що не тарифікується: коди помилок та правила тарифікації

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

Коди стану HTTP та правила тарифікації

Правила визначення тарифікації та обробки відповідей на рівні HTTP такі:

Примітка: під час доступу через Cloudflare сервіс 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 (очищений блок) та -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 (ключі в шляху та токени 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: ємність burst накопичувача токенів у 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.
• Інформацію про ціни планів та деталі розрахунків див. на Сторінці цін.
• Перехід на платний план: здійснення платного поповнення знімає обмеження кількості викликів на секунду безкоштовного плану (Free Plan); для кожного ключа продовжують діяти ліміти швидкості та burst у CU.

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

Якщо балансу вашого акаунта недостатньо або вам потрібна вища пропускна здатність, поповніть рахунок ончейн у консолі за такими кроками:

1. Увійдіть до Консолі: авторизуйтеся в Консолі BlockVectra.
2. Перейдіть на сторінку Billing: відкрийте сторінку Billing.
3. Отримайте виділену адресу: у блоці ончейн-поповнення скопіюйте виділену адресу поповнення для вашого акаунта або відскануйте QR-код.
4. Перекажіть кошти: переказуйте кошти лише за допомогою підтримуваних мереж та USDC / USDT / USDG, перелічених на сторінці. Підтримувані мережі та мінімальні суми поповнення наведені в консолі.
5. Автоматичне зарахування: після виявлення ончейн транзакції відображаються як «Processing»; після зарахування кредити автоматично додаються до вашого балансу.

Важливі примітки:

• Використовуйте лише ті мережі та токени, які явно вказані в консолі. Перекази в непідтримуваних мережах або з неправильними токенами не можуть бути зараховані автоматично.
• Переконайтеся, що кожен переказ відповідає мінімальній сумі поповнення, вказаній у консолі.
• Після зарахування першого платного депозиту ваш акаунт оновлюється до платного, що знімає ліміт викликів на секунду безкоштовного плану.

Програми агентів або серверів можуть викликати ендпоінти поповнення безпосередньо за допомогою API key; див. Посібник з програмного поповнення для агентів.

Тарифікація Push через Webhook

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

Див. Посібник з Blockchain Webhook API для налаштування, перевірку підпису та відновлення доставки. У посібнику з платежів у стейблкоїнах розглядається перевірка чеків та бекфіл через опитування; підписки через WebSocket мають власний облік підключень і сповіщень. Помилки запитів перелічено в довіднику помилок. Вага нижче отримана з GET /v1/plans.

Наступні кроки

• Перегляньте каталог наборів даних, щоб побачити кожен набір даних, який індексує BlockVectra.
• Ознайомтеся з безкоштовним планом та цінами, щоб перевірити, що включено у ваш акаунт.
• Увійдіть до консолі, щоб створити API key.