Rate Limits, Errors and Billing

This page is the reference for the three things that stop an integration working: running out of requests, getting an error back, and running out of credits. It also shows where to watch all three from your account.

Reach for it when a call that worked yesterday returns a code you do not recognise, when you are sizing how many requests your app can make, or when you want to know exactly what a call will cost before you ship it.

Rate limits

Limits are set 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 or 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 with no approval step. Premium and pro are assigned by Cognivo, and partner and enterprise limits are set per agreement. Standard RateLimit-* headers come back on every call, so you can see your remaining budget without guessing. When the budget runs out you get 429 rate_limited with a Retry-After header telling you when to try again.

Watching your usage

Sign in to the dApp, open Account in the left sidebar, choose Developers, then open the Usage tab.

The Usage tab on the Developers page, shown for a key that has not been used yet.Enlarge image

The window selector at the top switches between Last 24 hours, Last 7 days and Last 30 days. Next to it, a chip shows your credit balance and another shows the rate tier and hourly limit that applies to your keys. Below that, five counters break the window down into Requests, Successful, Errors, Rate limited and Credits used, and the Outcome breakdown card splits the same window three ways.

Quoted vs charged is the panel to read before you worry about a bill. In the product's own words, "Quoted is the list price. Charged is what actually came out of your balance." The two numbers are not always the same, because failed calls, denied calls and honest empty answers are quoted but never charged.

Request history lists individual calls and can be filtered by key, endpoint and status. Two empty states mean different things. "No requests match these filters." means calls exist in this window but none match what you filtered to, so widen the filters. "No usage in this window yet." means no call from any of your keys landed in this window at all. Neither is an error, and neither means a call was lost. If you expected traffic and see zero, check that your app is using the key you think it is, and widen the window.

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, and addresses must be 0x plus 40 hex characters.
401	missing_api_key	No X-API-Key or Bearer token presented.
401	invalid_api_key	Key unknown, or not a Cognivo v2 key.
402	payment_required	Not enough Cognivo credits for this call. Nothing was charged.
403	access_required	A legacy metadata only key tried a live call.
403	sandbox_limited	A sandbox (cogv_test_) key tried a live intelligence call.
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 endpoint.
403	chain_denied	The key is restricted to certain networks and this request named a different one. Refused before any upstream call and before any allowance is used.
403	key_expired	The key's expiry has passed. It is refused everywhere, including GET /v1/api/me.
403	suspended_key	The key is suspended and cannot execute. The portal shows the reason.
403	revoked_api_key	The key was revoked or rotated away.
403	project_disabled	The owning project is suspended or archived.
403	scope_denied	The key lacks the scope this endpoint needs.
403	origin_denied	An Origin or IP allow list is configured on the key and this request did not match it.
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 you contact support.
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	A rare billing or dependency hiccup. Nothing was charged, so retry.

Every response carries request_id, and successful responses repeat it as meta.request_id. Keep it. Support can trace a single call from that one value.

Common errors and how to fix them

• 401 missing_api_key. The key never reached us. Send it in the X-API-Key header, spelled exactly, or as Authorization: Bearer YOUR_API_KEY, and check that no proxy is stripping the header.
• 401 invalid_api_key. The key must start with cogv_live_ or cogv_test_. Copy 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. Top up on your Cognivo billing page, then retry. Nothing was charged. GET /v1/api/me shows your current balance.
• 403 revoked_api_key. Take the newest key from the portal. The old one will never work again.
• 403 scope_denied. The key works but lacks the scope this endpoint needs, for example security:read for wallet/approvals. See Authentication and API keys.
• 403 origin_denied. Call from an allow listed origin or 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.
• 403 sandbox_limited. Sandbox keys are for testing and cannot run live intelligence. Create a live key.
• 403 chain_denied. Check allowed_chains on GET /v1/api/me. A null there means no restriction. Nothing was charged.
• 403 trial_expired or trial_exhausted. The optional evaluation allowance has ended. You do not need a trial, so switch to an ordinary live key.
• 403 endpoint_denied. Your arrangement covers other endpoints but not this one. Ask to have it included.
• 403 suspended_key. The portal shows the reason. Contact support from the dApp with your request_id if it is unclear.
• 429 rate_limited. Honour the Retry-After header and add client side queueing with backoff, or ask about a higher limit.
• 400 invalid_chain. Use eth, base or bsc. Names like ethereum and numeric chain ids are not accepted.
• 400 invalid_address, invalid_wallet, invalid_token. Send a full 0x plus 40 hex character address. The API does not resolve ENS names or token symbols.
• 422 insufficient_data. Not an outage and not your mistake. The tool ran but could not ground a fair answer, for example wallet/pnl on a wallet with no priced trades in that token. It means Cognivo could not verify the answer, not that the answer is zero. You are never charged for a 422.
• 404 public_api_disabled. The public API is temporarily switched off. This is not a wrong URL, so try again later.

Credits and billing

Live keys are self serve. There is no application and no subscription. A new live key works immediately, and each successful call deducts that endpoint's credit price from the project owner's Cognivo credit balance, the same credits Chat and the dApp use. Every account gets 5 free credits per day, and they reset at midnight UTC. Charging for Developer API calls is switched off today, so a successful call deducts nothing and your balance does not move.

Each endpoint's price in credits is printed next to it on the Endpoints tab of the Developers page, and free endpoints are labelled Free there. Read the price from the portal rather than hard coding it.

• Failed calls are never charged. Errors, timeouts, denied calls and rate limits cost nothing.
• A successful call is charged exactly once, so retries are safe.
• Honest empty results are free. A 422, and an empty wallet/approvals list, are valid answers and are not charged.
• Out of credits gives you 402 payment_required with nothing charged. Top up in the dApp, then retry.
• Sandbox (cogv_test_) keys are never charged and cannot run live intelligence.
• Suspended keys and disabled projects cannot execute anything and are never charged.
• Enterprise is the request path for custom pricing, custom limits and volume, and you request it from the dApp.

Reading the results honestly

API results describe what Cognivo checked and what it found on chain. A clean result is not proof that a token or wallet is safe, and a flagged result is not proof of fraud. A missing or unavailable field means Cognivo could not verify that item, not that there is nothing there. Treat every response as one input to your own research.

Next steps

Look up parameters, scopes and example responses in the Endpoint reference, tighten your keys with Authentication and API keys, or see how credits work across the rest of the product in Billing and credits.