Rate limits, errors and billing

Rate limits

Limits are per key, by access mode:

Access mode	Limit
live paid: basic (default for every new live key)	1,000 requests/hour
live paid: premium (admin-assigned)	5,000 requests/hour
live paid: pro (admin-assigned)	15,000 requests/hour
partner / enterprise	admin-configured
any cogv_test_ sandbox key	25 requests/hour, 100/day, 1/second
metadata surface (health, me, discover) with any valid key	60 requests/hour, 1/second

A new live key starts at basic (1,000 requests/hour) with no approval step; premium and pro are admin-assigned, and partner and enterprise limits are configured per agreement. Standard RateLimit-* headers are returned; on exhaustion you get 429 rate_limited with a Retry-After header telling you when to try again.

Error codes

HTTP	error	Meaning
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	malformed input; chain must be eth, base or bsc; addresses must be 0x + 40 hex
401	missing_api_key	no X-API-Key (or Bearer) presented
401	invalid_api_key	key unknown or not a Cognivo v2 key
402	payment_required	not enough Cognivo credits for this call. Top up on your Cognivo account billing page and try again. Nothing was charged; failed calls are never charged
403	access_required	a legacy metadata-only key tried a live call - create a new self-serve live key to move to pay-as-you-go
403	sandbox_limited	a Sandbox (cogv_test_) key tried a live intelligence call; sandbox keys cannot run live intelligence
403	trial_expired	the key's optional trial allowance has expired
403	trial_exhausted	the key's optional trial allowance is fully used
403	endpoint_denied	the key's access arrangement does not cover this specific endpoint
403	suspended_key	the key is suspended and cannot execute; the portal shows the reason
403	revoked_api_key	key was revoked or rotated away
403	project_disabled	the owning project is suspended or archived
403	scope_denied	key lacks the scope this endpoint needs
403	origin_denied	Origin/IP allow-list configured on the key and not matched
404	public_api_disabled	the public API is temporarily switched off
422	insufficient_data (and similar)	the tool ran but could not ground a fair result - you are not charged
429	rate_limited	rate budget exhausted; the response carries Retry-After
500	internal_error	unexpected failure - include request_id when contacting support
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	rare billing or dependency hiccup - nothing was charged, simply retry

Every response carries request_id (also meta.request_id on success). Keep it; support can trace a call from it.

Common errors and how to fix them

• 401 missing_api_key - the key never reached us. Send it in the X-API-Key header (exact name) or as Authorization: Bearer YOUR_API_KEY, and check that a proxy or framework is not stripping the header.
• 401 invalid_api_key - the key is not recognized. It must start with cogv_live_ or cogv_test_; check you copied the whole key with no surrounding whitespace. If you lost the original, rotate the key in the portal and use the new one.
• 402 payment_required - not enough Cognivo credits for this call. Top up on your Cognivo account billing page and try again; nothing was charged, and failed calls are never charged. GET /v1/api/me shows your current balance.
• 403 revoked_api_key - this key was revoked or rotated away. Grab the newest key from the portal; the old one will never work again.
• 403 scope_denied - the key works, but it lacks the scope this endpoint needs (for example security:read for wallet/approvals). Edit the key's scopes or create a key with the right scope; see Authentication and API keys.
• 403 origin_denied - the key has an Origin or IP allow-list and this request came from somewhere else. Call from an allow-listed origin/IP, or clear the lists on the key.
• 403 access_required - this is a legacy metadata-only key from before self-serve billing. Create a new live key in the portal; it works immediately, pay-as-you-go, with no approval step.
• 403 sandbox_limited - a Sandbox (cogv_test_) key tried a live intelligence call. Sandbox keys are for limited demos and testing only; create a live key, which works immediately.
• 403 trial_expired / trial_exhausted - your optional evaluation allowance has ended (time or usage). You do not need a trial: switch to an ordinary live key and pay-as-you-go, or ask about enterprise for volume.
• 403 endpoint_denied - your access arrangement covers other endpoints but not this one (endpoint-specific access is common on partner/enterprise arrangements). Ask to have this endpoint included.
• 403 suspended_key - the key is suspended and cannot execute. The portal shows the reason; contact support from the dApp with your request_id if it is unclear.
• 429 rate_limited - you used up this key's budget. Honor the Retry-After header, add client-side queueing with backoff, or ask about a higher limit. Remember cogv_test_ sandbox keys are capped at 25 requests/hour, 100/day and 1/second; the metadata surface is capped at 60/hour with a 1/second burst cap.
• 400 invalid_chain - chain must be eth, base or bsc. Names like ethereum or numeric chain ids like 8453 are not accepted.
• 400 invalid_address / invalid_wallet / invalid_token - send a full 0x + 40 hex character address. ENS names and token symbols are not resolved by the API.
• 422 insufficient_data - not an outage and not your fault: the tool ran but could not ground a fair answer (for example wallet/pnl on a wallet with no priced trades in that token). You are never charged for a 422; try a different wallet/token or a wider question.
• 503 pricing_mismatch / billing_unavailable / billing_commit_failed - a rare billing hiccup. Nothing was charged; simply retry the call.
• 404 public_api_disabled - the public API is temporarily switched off, not a wrong URL. Try again later or check the announcements channel.

Billing, credits and top-ups

Live keys are self-serve and pay-as-you-go. There is no application, no trial requirement and no subscription: a new live key works immediately and each successful call deducts the endpoint's credit price from the project owner's Cognivo credit balance (the same credits as Chat and the dApp).

• Failed calls are never charged. Errors, timeouts, denied calls and rate limits cost nothing.
• A successful call is charged exactly once. Duplicate submissions of the same operation cannot double-charge you, so retries are safe.
• Honest empty results are free. A 422 (for example wallet/pnl with no priced trades) and an empty wallet/approvals list are valid answers and are not charged.
• Out of credits? You get 402 payment_required and nothing is charged. Top up on your Cognivo account billing page in the dApp, then retry. GET /v1/api/me shows your credits_balance and top_up guidance.
• Sandbox (cogv_test_) keys are never charged: they are for limited demos and integration testing and cannot run live intelligence.
• Trial is an optional, admin-granted evaluation allowance - not needed for ordinary paid use. Partner is admin-managed. Enterprise is the request path for custom pricing, custom limits and volume - request it from the dApp.
• Suspended keys and disabled projects cannot execute anything and are never charged; the portal shows the reason.

Credit prices per successful call:

Endpoint	Credits per successful call
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	free
discover	free, with a tight rate cap

Not financial advice

API results are on-chain intelligence signals, not investment advice, and absence of a red flag is not proof of safety. Always do your own research.