Limites de taxa, erros e cobrança

Limites de taxa

Os limites são por chave, conforme o modo de acesso:

Modo de acesso	Limite
free (metadados: health, me, discover)	60 requisições/hora, com um teto de rajada de 1/segundo
basic (pago, quando ativo)	1.000 requisições/hora
premium (pago, quando ativo)	5.000 requisições/hora
pro (pago, quando ativo)	15.000 requisições/hora
partner / enterprise	configurado por um administrador
qualquer chave sandbox cogv_test_	25 requisições/hora e 100/dia

Chaves novas começam apenas com acesso gratuito a metadados. O acesso trial é concedido por um administrador, limitado e com prazo de expiração; os limites de partner e enterprise são configurados conforme o acordo - solicite acesso pelo dApp. Os cabeçalhos padrão RateLimit-* são retornados; ao esgotar o limite, você recebe 429 rate_limited.

Códigos de erro

HTTP	error	Significado
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	entrada malformada; a chain deve ser eth, base ou bsc; endereços devem ser 0x + 40 hex
401	missing_api_key	nenhum X-API-Key (ou Bearer) apresentado
401	invalid_api_key	chave desconhecida ou que não é uma chave v2 da Cognivo
402	insufficient_credits	uso pago: seu saldo de créditos Cognivo não cobre a chamada (nada foi cobrado)
402	payment_required	este endpoint precisa de acesso pago nesta chave e nenhuma via de pagamento válida cobre a chamada (nada foi cobrado)
403	access_required	a chave não tem concessão de acesso para os endpoints de inteligência ao vivo - solicite acesso trial, partner, pago ou enterprise
403	sandbox_limited	uma chave sandbox (cogv_test_) tentou uma chamada ao vivo fora da sua cota de demo habilitada por um administrador
403	trial_expired	o acesso trial da chave expirou
403	trial_exhausted	a cota trial da chave foi totalmente consumida
403	endpoint_denied	a concessão de acesso da chave não cobre este endpoint específico
403	suspended_key	a chave foi suspensa por um administrador
403	revoked_api_key	a chave foi revogada ou substituída por rotação
403	project_disabled	o projeto dono está suspenso ou arquivado
403	scope_denied	a chave não tem o escopo de que este endpoint precisa
403	origin_denied	há uma lista de permissão de Origin/IP configurada na chave e não houve correspondência
404	public_api_disabled	a API pública está temporariamente desligada
422	insufficient_data (e similares)	a ferramenta executou mas não conseguiu fundamentar um resultado justo - você não é cobrado
429	rate_limited	orçamento horário do tier esgotado
500	internal_error	falha inesperada - inclua o request_id ao contatar o suporte
503	billing_unavailable / unavailable	indisponibilidade temporária de uma dependência - tente novamente mais tarde, nada é cobrado

Toda resposta carrega um request_id (também meta.request_id em caso de sucesso). Guarde-o; o suporte pode rastrear uma chamada a partir dele.

Erros comuns e como corrigi-los

• 401 missing_api_key - a chave nunca chegou até nós. Envie-a no cabeçalho X-API-Key (nome exato) ou como Authorization: Bearer YOUR_API_KEY, e verifique se um proxy ou framework não está removendo o cabeçalho.
• 401 invalid_api_key - a chave não é reconhecida. Ela deve começar com cogv_live_ ou cogv_test_; confira se você copiou a chave inteira sem espaços em volta. Se perdeu a original, rotacione a chave no portal e use a nova.
• 403 revoked_api_key - esta chave foi revogada ou substituída por rotação. Pegue a chave mais recente no portal; a antiga nunca mais vai funcionar.
• 403 scope_denied - a chave funciona, mas não tem o escopo de que este endpoint precisa (por exemplo security:read para wallet/approvals). Edite os escopos da chave ou crie uma chave com o escopo certo; veja Autenticação e chaves de API.
• 403 origin_denied - a chave tem uma lista de permissão de Origin ou IP e esta requisição veio de outro lugar. Chame a partir de uma origem/IP na lista de permissão, ou limpe as listas da chave.
• 403 access_required - a chave é válida mas não tem concessão de acesso para os endpoints de inteligência ao vivo. Solicite acesso trial, partner, pago ou enterprise pelo portal do desenvolvedor; sem ele a chamada nunca executa (e nunca cobra).
• 403 sandbox_limited - uma chave sandbox (cogv_test_) tentou uma chamada de inteligência ao vivo fora da sua cota de demo. Peça a um administrador para habilitar a cota de demo ao vivo para a chave, ou use uma chave live com acesso.
• 403 trial_expired / trial_exhausted - seu trial terminou (por tempo ou por cota). Solicite uma extensão ou migre para acesso pago, partner ou enterprise.
• 403 endpoint_denied - sua concessão de acesso cobre outros endpoints, mas não este (acesso específico por endpoint é comum em concessões partner/enterprise). Solicite acesso a este endpoint.
• 403 suspended_key - a chave foi suspensa por um administrador. Fale com o suporte pelo dApp com o seu request_id.
• 402 payment_required - esta chamada precisa de acesso pago nesta chave. Recarregue créditos Cognivo ou solicite um modo de acesso que cubra o endpoint; nada foi cobrado.
• 429 rate_limited - você esgotou o orçamento desta chave. Reduza o ritmo, adicione enfileiramento com backoff no lado do cliente, ou solicite um modo de acesso maior. Lembre-se de que chaves sandbox cogv_test_ são limitadas a 25 requisições/hora e 100/dia; o acesso gratuito a metadados é limitado a 60/hora com um teto de rajada de 1/segundo.
• 400 invalid_chain - chain deve ser eth, base ou bsc. Nomes como ethereum ou ids numéricos de chain como 8453 não são aceitos.
• 400 invalid_address / invalid_wallet / invalid_token - envie um endereço completo 0x + 40 caracteres hexadecimais. Nomes ENS e símbolos de tokens não são resolvidos pela API.
• 422 insufficient_data - não é uma indisponibilidade nem culpa sua: a ferramenta executou mas não conseguiu fundamentar uma resposta justa (por exemplo wallet/pnl em uma carteira sem trades precificados naquele token). Você nunca é cobrado por um 422; tente outra carteira/token ou uma pergunta mais ampla.
• 404 public_api_disabled - a API pública está temporariamente desligada, não é uma URL errada. Tente mais tarde ou confira o canal de anúncios.

Acesso, cobrança e créditos

A Developer API é controlada por acesso durante o acesso antecipado. Uma chave gratuita pode explorar: ler a documentação, chamar GET /v1/api/health, inspecionar a si mesma com GET /v1/api/me e fazer chamadas limitadas de sandbox/demo. Os endpoints de inteligência ao vivo exigem acesso trial, partner, pago ou enterprise; sem ele, eles retornam um erro claro (access_required, trial_expired, payment_required e similares) em vez de executar de graça.

• O uso pago é cobrado em créditos Cognivo por chamada bem-sucedida, do seu saldo existente de créditos Cognivo (os mesmos créditos do Chat/Telegram), gastos pela conta do dono do projeto. Falhas, timeouts, resultados vazios e erros não são cobrados.
• As cobranças são idempotentes - uma requisição repetida ou duplicada não pode ser cobrada duas vezes.
• As chaves sandbox (cogv_test_) são para testes de integração: limitadas a 25 requisições/hora e 100/dia, e só conseguem executar uma pequena cota de demo ao vivo quando um administrador a habilita.
• O acesso trial é concedido por um administrador, limitado e com prazo de expiração.
• Enterprise é sob medida: preços, limites maiores e acesso específico por endpoint - solicite acesso pelo dApp.

Custos em créditos por endpoint (aplicam-se ao uso pago; exibidos por transparência):

Endpoint	Créditos por chamada bem-sucedida
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	gratuito
discover	gratuito, com um teto de taxa rígido

Não é aconselhamento financeiro

Os resultados da API são sinais de inteligência on-chain, não aconselhamento de investimento, e a ausência de uma red flag não é prova de segurança. Sempre faça a sua própria pesquisa.