Лимиты запросов, ошибки и биллинг
Эта страница - справочник по трём вещам, которые ломают интеграцию: закончились запросы, вернулась ошибка, закончились кредиты. Здесь также показано, где следить за всеми тремя из вашего аккаунта.
Обращайтесь к ней, когда вызов, работавший вчера, возвращает незнакомый код, когда вы оцениваете, сколько запросов может делать ваше приложение, или когда хотите точно знать, во сколько обойдётся вызов, прежде чем выпускать код.
Лимиты запросов
Лимиты задаются для каждого ключа, по режиму доступа:
| Режим доступа | Лимит |
|---|---|
| live платный: basic (по умолчанию для каждого нового live-ключа) | 1,000 запросов/час |
| live платный: premium (назначается администратором) | 5,000 запросов/час |
| live платный: pro (назначается администратором) | 15,000 запросов/час |
| partner или enterprise | настраивается администратором |
любой песочный ключ cogv_test_ | 25 запросов/час, 100/день, 1/секунду |
поверхность метаданных (health, me, discover) с любым действительным ключом | 60 запросов/час, 1/секунду |
Новый live-ключ начинает с уровня basic без шага одобрения. Premium и pro назначаются Cognivo, а лимиты partner и enterprise устанавливаются по договорённости. Стандартные заголовки RateLimit-* возвращаются при каждом вызове, поэтому вы видите остаток бюджета без догадок. Когда бюджет исчерпан, вы получаете 429 rate_limited с заголовком Retry-After, сообщающим, когда пробовать снова.
Наблюдение за использованием
Войдите в dApp, откройте Account в левой боковой панели, выберите Developers, затем откройте вкладку Usage.
Селектор окна вверху переключает между Last 24 hours, Last 7 days и Last 30 days. Рядом один чип показывает ваш баланс кредитов, а другой - тарифный уровень и часовой лимит, который применяется к вашим ключам. Ниже пять счётчиков разбивают окно на Requests, Successful, Errors, Rate limited и Credits used, а карточка Outcome breakdown делит то же окно на три части.
Quoted vs charged - это панель, которую стоит прочитать, прежде чем беспокоиться о счёте. Словами самого продукта: «Quoted is the list price. Charged is what actually came out of your balance.» Эти два числа не всегда совпадают, потому что неудачные вызовы, отклонённые вызовы и честные пустые ответы котируются, но никогда не тарифицируются.
Request history перечисляет отдельные вызовы, и её можно фильтровать по ключу, эндпоинту и статусу. Два пустых состояния означают разное. «No requests match these filters.» значит, что вызовы в этом окне есть, но ни один не подходит под ваш фильтр, поэтому расширьте фильтры. «No usage in this window yet.» значит, что в это окно вообще не попал ни один вызов ни с одного из ваших ключей. Ни то, ни другое не является ошибкой, и ни то, ни другое не означает, что вызов потерялся. Если вы ожидали трафик, а видите ноль, проверьте, что ваше приложение использует именно тот ключ, о котором вы думаете, и расширьте окно.
Коды ошибок
| HTTP | error | Значение |
|---|---|---|
| 400 | bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token | Некорректный ввод. chain должен быть eth, base или bsc, а адреса должны быть 0x плюс 40 шестнадцатеричных символов. |
| 401 | missing_api_key | Не передан ни X-API-Key, ни Bearer-токен. |
| 401 | invalid_api_key | Ключ неизвестен или не является ключом Cognivo v2. |
| 402 | payment_required | Недостаточно кредитов Cognivo для этого вызова. Ничего не списано. |
| 403 | access_required | Устаревший ключ только для метаданных попытался сделать живой вызов. |
| 403 | sandbox_limited | Песочный ключ (cogv_test_) попытался сделать живой вызов аналитики. |
| 403 | trial_expired | Необязательная пробная квота ключа истекла. |
| 403 | trial_exhausted | Необязательная пробная квота ключа полностью израсходована. |
| 403 | endpoint_denied | Условия доступа ключа не покрывают этот эндпоинт. |
| 403 | chain_denied | Ключ ограничен определёнными сетями, а этот запрос назвал другую. Отклонено до любого внешнего вызова и до расходования какой-либо квоты. |
| 403 | key_expired | Срок действия ключа истёк. Он отклоняется везде, включая GET /v1/api/me. |
| 403 | suspended_key | Ключ приостановлен и не может выполняться. Портал показывает причину. |
| 403 | revoked_api_key | Ключ был отозван или заменён ротацией. |
| 403 | project_disabled | Владеющий проект приостановлен или архивирован. |
| 403 | scope_denied | У ключа нет скоупа, который нужен этому эндпоинту. |
| 403 | origin_denied | На ключе настроен список разрешённых Origin или IP, и этот запрос ему не соответствовал. |
| 404 | public_api_disabled | Публичный API временно выключен. |
| 422 | insufficient_data и подобные | Инструмент отработал, но не смог обосновать честный результат. С вас не списывают. |
| 429 | rate_limited | Бюджет запросов исчерпан. В ответе есть Retry-After. |
| 500 | internal_error | Непредвиденный сбой. Приложите request_id, когда обращаетесь в поддержку. |
| 503 | pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable | Редкий сбой биллинга или зависимости. Ничего не списано, поэтому повторите. |
Каждый ответ несёт request_id, а успешные ответы дублируют его как meta.request_id. Сохраняйте его. Поддержка может отследить отдельный вызов по одному этому значению.
Частые ошибки и как их исправить
- 401
missing_api_key. Ключ до нас не дошёл. Отправляйте его в заголовкеX-API-Key, написанном в точности так, или какAuthorization: Bearer YOUR_API_KEY, и проверьте, что заголовок не вырезает какой-нибудь прокси. - 401
invalid_api_key. Ключ должен начинаться сcogv_live_илиcogv_test_. Копируйте ключ целиком, без пробелов по краям. Если вы потеряли оригинал, выполните ротацию ключа в портале и используйте новый. - 402
payment_required. Пополните баланс на странице биллинга Cognivo, затем повторите. Ничего не было списано.GET /v1/api/meпоказывает ваш текущий баланс. - 403
revoked_api_key. Возьмите самый новый ключ из портала. Старый больше никогда не заработает. - 403
scope_denied. Ключ работает, но у него нет скоупа, нужного этому эндпоинту, напримерsecurity:readдляwallet/approvals. Смотрите Аутентификация и API-ключи. - 403
origin_denied. Вызывайте с разрешённого origin или IP, либо очистите списки на ключе. - 403
access_required. Это устаревший ключ только для метаданных, созданный до self-serve биллинга. Создайте новый live-ключ в портале. - 403
sandbox_limited. Песочные ключи предназначены для тестирования и не могут выполнять живую аналитику. Создайте live-ключ. - 403
chain_denied. Проверьтеallowed_chainsчерезGET /v1/api/me. Значениеnullтам означает отсутствие ограничения. Ничего не было списано. - 403
trial_expiredилиtrial_exhausted. Необязательная оценочная квота закончилась. Пробный режим вам не нужен, поэтому перейдите на обычный live-ключ. - 403
endpoint_denied. Ваши условия покрывают другие эндпоинты, но не этот. Попросите включить его. - 403
suspended_key. Портал показывает причину. Если она непонятна, обратитесь в поддержку из dApp со своимrequest_id. - 429
rate_limited. Соблюдайте заголовокRetry-Afterи добавьте очередь на стороне клиента с экспоненциальной задержкой, либо спросите про повышенный лимит. - 400
invalid_chain. Используйтеeth,baseилиbsc. Названия вродеethereumи числовые идентификаторы сетей не принимаются. - 400
invalid_address,invalid_wallet,invalid_token. Отправляйте полный адрес:0xплюс 40 шестнадцатеричных символов. API не разрешает имена ENS и символы токенов. - 422
insufficient_data. Это не сбой и не ваша ошибка. Инструмент отработал, но не смог обосновать честный ответ, напримерwallet/pnlдля кошелька без сделок с ценой по этому токену. Это значит, что Cognivo не смог подтвердить ответ, а не что ответ равен нулю. За 422 с вас никогда не списывают. - 404
public_api_disabled. Публичный API временно выключен. Это не неверный URL, поэтому попробуйте позже.
Кредиты и биллинг
Live-ключи работают в режиме самообслуживания. Нет ни заявки, ни подписки. Новый live-ключ работает сразу, и каждый успешный вызов вычитает кредитную цену этого эндпоинта из баланса кредитов Cognivo владельца проекта, тех же кредитов, которые используют Chat и dApp. Каждый аккаунт получает 5 бесплатных кредитов в день, они обновляются в полночь UTC. Тарификация вызовов Developer API сегодня отключена, поэтому успешный вызов ничего не списывает и баланс не меняется.
Цена каждого эндпоинта в кредитах напечатана рядом с ним на вкладке Endpoints страницы Developers, а бесплатные эндпоинты помечены там как Free. Читайте цену из портала, а не прописывайте её в коде.
- Неудачные вызовы никогда не тарифицируются. Ошибки, таймауты, отклонённые вызовы и превышения лимита не стоят ничего.
- Успешный вызов тарифицируется ровно один раз, поэтому повторные попытки безопасны.
- Честные пустые результаты бесплатны. Ответ 422 и пустой список
wallet/approvals- это корректные ответы, и они не тарифицируются. - Кредиты закончились - вы получаете
402 payment_required, и ничего не списывается. Пополните баланс в dApp, затем повторите. - Песочные ключи (
cogv_test_) никогда не тарифицируются и не могут выполнять живую аналитику. - Приостановленные ключи и отключённые проекты не могут ничего выполнять и никогда не тарифицируются.
- Enterprise - это путь с заявкой для индивидуальных цен, индивидуальных лимитов и объёмов, и вы запрашиваете его из dApp.
Как честно читать результаты
Результаты API описывают, что Cognivo проверил и что он нашёл в блокчейне. Чистый результат не является доказательством того, что токен или кошелёк безопасны, а помеченный результат не является доказательством мошенничества. Отсутствующее или недоступное поле означает, что Cognivo не смог подтвердить этот пункт, а не что там ничего нет. Относитесь к каждому ответу как к одному из входных данных для вашего собственного исследования.
Дальнейшие шаги
Ищите параметры, скоупы и примеры ответов в Справочнике эндпоинтов, ужесточайте настройки ключей через Аутентификация и API-ключи или посмотрите, как кредиты работают в остальной части продукта, в Биллинг и кредиты.