Лимиты запросов, ошибки и биллинг

Лимиты запросов

Лимиты действуют на ключ, по режиму доступа:

Режим доступа	Лимит
live платный: basic (по умолчанию для каждого нового live-ключа)	1,000 запросов/час
live платный: premium (назначается администратором)	5,000 запросов/час
live платный: pro (назначается администратором)	15,000 запросов/час
партнёрский / enterprise	настраивается администратором
любой sandbox-ключ `cogv_test_`	25 запросов/час, 100/день, 1/секунду
поверхность метаданных (`health`, `me`, `discover`) с любым действительным ключом	60 запросов/час, 1/секунду

Новый live-ключ начинает с уровня basic (1,000 запросов/час) без какого-либо шага одобрения; premium и pro назначаются администратором, а лимиты партнёрского режима и enterprise настраиваются по соглашению. Возвращаются стандартные заголовки RateLimit-*; при исчерпании лимита вы получаете 429 rate_limited с заголовком Retry-After, который сообщает, когда пробовать снова.

Коды ошибок

HTTP	`error`	Значение
400	`bad_request` / `invalid_chain` / `invalid_address` / `invalid_wallet` / `invalid_token`	некорректный ввод; chain должен быть `eth`, `base` или `bsc`; адреса - `0x` + 40 hex
401	`missing_api_key`	не передан `X-API-Key` (или Bearer)
401	`invalid_api_key`	ключ неизвестен или не является ключом Cognivo v2
402	`payment_required`	недостаточно кредитов Cognivo для этого вызова. Пополните баланс на странице биллинга вашего аккаунта Cognivo и попробуйте снова. Ничего не списано; неудачные вызовы никогда не тарифицируются
403	`access_required`	legacy-ключ «только метаданные» попытался выполнить живой вызов - создайте новый self-serve live-ключ, чтобы перейти на pay-as-you-go
403	`sandbox_limited`	Sandbox-ключ (`cogv_test_`) попытался выполнить живой аналитический вызов; sandbox-ключи не могут выполнять живую аналитику
403	`trial_expired`	необязательная trial-квота ключа истекла
403	`trial_exhausted`	необязательная trial-квота ключа полностью израсходована
403	`endpoint_denied`	соглашение о доступе ключа не покрывает этот конкретный эндпоинт
403	`suspended_key`	ключ приостановлен и не может выполнять вызовы; портал показывает причину
403	`revoked_api_key`	ключ отозван или заменён ротацией
403	`project_disabled`	проект-владелец приостановлен или архивирован
403	`scope_denied`	у ключа нет скоупа, нужного этому эндпоинту
403	`origin_denied`	на ключе настроен allow-list 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 для этого вызова. Пополните баланс на странице биллинга вашего аккаунта Cognivo и попробуйте снова; ничего не списано, а неудачные вызовы никогда не тарифицируются. GET /v1/api/me показывает ваш текущий баланс.
403 revoked_api_key - этот ключ был отозван или заменён ротацией. Возьмите новейший ключ из портала; старый больше никогда не заработает.
403 scope_denied - ключ работает, но у него нет скоупа, нужного этому эндпоинту (например, security:read для wallet/approvals). Измените скоупы ключа или создайте ключ с нужным скоупом; см. Аутентификация и API-ключи.
403 origin_denied - у ключа есть allow-list по Origin или IP, а этот запрос пришёл откуда-то ещё. Вызывайте с разрешённого origin/IP или очистите списки на ключе.
403 access_required - это legacy-ключ «только метаданные» из времён до self-serve биллинга. Создайте новый live-ключ в портале; он работает сразу, pay-as-you-go, без шага одобрения.
403 sandbox_limited - Sandbox-ключ (cogv_test_) попытался выполнить живой аналитический вызов. Sandbox-ключи предназначены только для ограниченных демо и тестирования; создайте live-ключ, он работает сразу.
403 trial_expired / trial_exhausted - ваша необязательная оценочная квота закончилась (по времени или по использованию). Trial вам не нужен: перейдите на обычный live-ключ и pay-as-you-go или спросите об enterprise для объёмов.
403 endpoint_denied - ваше соглашение о доступе покрывает другие эндпоинты, но не этот (доступ к отдельным эндпоинтам типичен для партнёрских/enterprise-соглашений). Попросите включить этот эндпоинт.
403 suspended_key - ключ приостановлен и не может выполнять вызовы. Портал показывает причину; если она неясна, обратитесь в поддержку из dApp, указав ваш request_id.
429 rate_limited - вы израсходовали бюджет этого ключа. Соблюдайте заголовок Retry-After, добавьте клиентскую очередь с backoff или спросите о более высоком лимите. Помните, что sandbox-ключи cogv_test_ ограничены 25 запросами/час, 100/день и 1/секунду; поверхность метаданных ограничена 60/час с burst-лимитом 1/секунду.
400 invalid_chain - chain должен быть eth, base или bsc. Имена вроде ethereum или числовые chain id вроде 8453 не принимаются.
400 invalid_address / invalid_wallet / invalid_token - отправляйте полный адрес 0x + 40 hex-символов. ENS-имена и символы токенов API не резолвит.
422 insufficient_data - это не сбой и не ваша вина: инструмент отработал, но не смог обосновать честный ответ (например, wallet/pnl по кошельку без оценённых сделок в этом токене). За 422 плата никогда не взимается; попробуйте другой кошелёк/токен или более широкий вопрос.
503 pricing_mismatch / billing_unavailable / billing_commit_failed - редкий сбой биллинга. Ничего не списано; просто повторите вызов.
404 public_api_disabled - публичный API временно отключён, это не неправильный URL. Повторите позже или загляните в канал анонсов.

Биллинг, кредиты и пополнения

Live-ключи работают по модели self-serve и pay-as-you-go. Нет ни заявки, ни требования trial, ни подписки: новый live-ключ работает сразу, и каждый успешный вызов списывает цену эндпоинта в кредитах с баланса кредитов Cognivo владельца проекта (те же кредиты, что в Chat и dApp).

Неудачные вызовы никогда не тарифицируются. Ошибки, таймауты, отклонённые вызовы и лимиты не стоят ничего.
Успешный вызов тарифицируется ровно один раз. Задублированные отправки одной и той же операции не могут списать дважды, поэтому повторы безопасны.
Честные пустые результаты бесплатны. 422 (например, wallet/pnl без оценённых сделок) и пустой список wallet/approvals - валидные ответы, и они не тарифицируются.
Кончились кредиты? Вы получаете 402 payment_required, и ничего не списывается. Пополните баланс на странице биллинга вашего аккаунта Cognivo в dApp, затем повторите. GET /v1/api/me показывает ваш credits_balance и подсказку top_up.
Sandbox-ключи (cogv_test_) никогда не тарифицируются: они предназначены для ограниченных демо и интеграционного тестирования и не могут выполнять живую аналитику.
Trial - необязательная оценочная квота, выдаваемая администратором - для обычного платного использования не нужна. Партнёрский режим управляется администратором. Enterprise - путь с запросом для индивидуальных цен, индивидуальных лимитов и объёмов - запросите его из dApp.
Приостановленные ключи и отключённые проекты не могут ничего выполнять и никогда не тарифицируются; портал показывает причину.

Цены в кредитах за успешный вызов:

Эндпоинт	Кредитов за успешный вызов
`intel/liquidity`	2
`intel/risk`	2
`wallet/approvals`	2
`intel/why-down`	3
`intel/team-wallets`	5
`wallet/exact-movements`	5
`wallet/pnl`	10
`health`, `me`	бесплатно
`discover`	бесплатно, с жёстким лимитом запросов

Не финансовый совет

Результаты API - это on-chain аналитические сигналы, а не инвестиционный совет, и отсутствие красного флага не является доказательством безопасности. Всегда проводите собственное исследование.