Limites de taxa, erros e cobrança

Esta página é a referência para as três coisas que travam uma integração: ficar sem requisições, receber um erro de volta e ficar sem créditos. Ela também mostra onde acompanhar as três a partir da sua conta.

Recorra a ela quando uma chamada que funcionava ontem retornar um código que você não reconhece, quando estiver dimensionando quantas requisições o seu app pode fazer, ou quando quiser saber exatamente quanto uma chamada vai custar antes de colocá-la em produção.

Limites de taxa

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

Modo de acesso	Limite
live pago: basic (padrão para toda nova chave live)	1.000 requisições/hora
live pago: premium (atribuído por administrador)	5.000 requisições/hora
live pago: pro (atribuído por administrador)	15.000 requisições/hora
partner ou enterprise	configurado por administrador
qualquer chave de sandbox cogv_test_	25 requisições/hora, 100/dia, 1/segundo
superfície de metadados (health, me, discover) com qualquer chave válida	60 requisições/hora, 1/segundo

Uma nova chave live começa no basic sem etapa de aprovação. Premium e pro são atribuídos pela Cognivo, e os limites de partner e enterprise são definidos conforme o acordo. Os cabeçalhos padrão RateLimit-* voltam em toda chamada, então você consegue ver o seu orçamento restante sem adivinhar. Quando o orçamento acaba, você recebe 429 rate_limited com um cabeçalho Retry-After indicando quando tentar de novo.

Acompanhando seu uso

Entre no dApp, abra Conta na barra lateral esquerda, escolha Developers e abra a aba Usage.

A aba Usage na página Developers, exibida para uma chave que ainda não foi usada.Ampliar imagem

O seletor de janela no topo alterna entre Últimas 24 horas, Últimos 7 dias e Últimos 30 dias. Ao lado dele, um chip mostra o seu saldo de créditos e outro mostra o nível de taxa e o limite por hora que se aplicam às suas chaves. Abaixo, cinco contadores dividem a janela em Requisições, Bem-sucedidas, Erros, Limitadas por taxa e Créditos usados, e o card Detalhamento por resultado divide a mesma janela em três partes.

Cotado x cobrado é o painel para ler antes de se preocupar com uma fatura. Nas palavras do próprio produto, "Cotado é o preço de tabela. Cobrado é o que realmente saiu do seu saldo." Os dois números nem sempre são iguais, porque chamadas com falha, chamadas negadas e respostas honestamente vazias são cotadas, mas nunca cobradas.

O Histórico de requisições lista chamadas individuais e pode ser filtrado por chave, endpoint e status. Dois estados vazios significam coisas diferentes. "Nenhuma requisição corresponde a estes filtros." significa que existem chamadas nesta janela, mas nenhuma corresponde ao filtro aplicado, então amplie os filtros. "Ainda não há uso nesta janela." significa que nenhuma chamada de nenhuma das suas chaves caiu nesta janela. Nenhum dos dois é um erro, e nenhum significa que uma chamada foi perdida. Se você esperava tráfego e vê zero, verifique se o seu app está usando a chave que você imagina e amplie a janela.

Códigos de erro

HTTP	error	Significado
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	Entrada malformada. chain deve ser eth, base ou bsc, e os endereços devem ser 0x mais 40 caracteres hexadecimais.
401	missing_api_key	Nenhum X-API-Key ou token Bearer foi apresentado.
401	invalid_api_key	Chave desconhecida ou que não é uma chave v2 da Cognivo.
402	payment_required	Créditos Cognivo insuficientes para esta chamada. Nada foi cobrado.
403	access_required	Uma chave antiga apenas de metadados tentou uma chamada live.
403	sandbox_limited	Uma chave de sandbox (cogv_test_) tentou uma chamada de inteligência live.
403	trial_expired	A cota opcional de trial da chave expirou.
403	trial_exhausted	A cota opcional de trial da chave foi totalmente usada.
403	endpoint_denied	O acordo de acesso da chave não cobre este endpoint.
403	chain_denied	A chave está restrita a certas redes e esta requisição indicou uma diferente. Recusada antes de qualquer chamada upstream e antes de usar qualquer cota.
403	key_expired	A expiração da chave passou. Ela é recusada em todos os lugares, incluindo GET /v1/api/me.
403	suspended_key	A chave está suspensa e não pode executar. O portal mostra o motivo.
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 exigido por este endpoint.
403	origin_denied	Há uma lista de permissão de Origin ou de IP configurada na chave e esta requisição não correspondeu a ela.
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 de taxa esgotado. A resposta traz Retry-After.
500	internal_error	Falha inesperada. Inclua o request_id ao entrar em contato com o suporte.
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	Uma falha rara de cobrança ou de dependência. Nada foi cobrado, então tente de novo.

Toda resposta carrega um request_id, e as respostas bem-sucedidas o repetem em meta.request_id. Guarde esse valor. O suporte consegue rastrear uma chamada específica só com ele.

Erros comuns e como resolvê-los

• 401 missing_api_key. A chave nunca chegou até nós. Envie-a no cabeçalho X-API-Key, escrito exatamente assim, ou como Authorization: Bearer YOUR_API_KEY, e verifique se nenhum proxy está removendo o cabeçalho.
• 401 invalid_api_key. A chave precisa começar com cogv_live_ ou cogv_test_. Copie a chave inteira, sem espaços em volta. Se você perdeu a original, rotacione a chave no portal e use a nova.
• 402 payment_required. Faça uma recarga na sua página de Billing da Cognivo e tente de novo. Nada foi cobrado. GET /v1/api/me mostra o seu saldo atual.
• 403 revoked_api_key. 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 exigido por este endpoint, por exemplo security:read para wallet/approvals. Veja Autenticação e chaves de API.
• 403 origin_denied. Chame a partir de uma origem ou IP na lista de permissão, ou limpe as listas na chave.
• 403 access_required. Esta é uma chave antiga, apenas de metadados, anterior à cobrança em autoatendimento. Crie uma nova chave live no portal.
• 403 sandbox_limited. Chaves de sandbox servem para testes e não conseguem executar inteligência live. Crie uma chave live.
• 403 chain_denied. Verifique allowed_chains em GET /v1/api/me. Um null ali significa nenhuma restrição. Nada foi cobrado.
• 403 trial_expired ou trial_exhausted. A cota opcional de avaliação terminou. Você não precisa de um trial, então mude para uma chave live comum.
• 403 endpoint_denied. O seu acordo cobre outros endpoints, mas não este. Peça para incluí-lo.
• 403 suspended_key. O portal mostra o motivo. Entre em contato com o suporte pelo dApp com o seu request_id se não estiver claro.
• 429 rate_limited. Respeite o cabeçalho Retry-After e adicione uma fila no lado do cliente com backoff, ou pergunte sobre um limite maior.
• 400 invalid_chain. Use eth, base ou bsc. Nomes como ethereum e ids numéricos de chain não são aceitos.
• 400 invalid_address, invalid_wallet, invalid_token. Envie um endereço completo, 0x mais 40 caracteres hexadecimais. A API não resolve nomes ENS nem símbolos de tokens.
• 422 insufficient_data. Não é uma indisponibilidade e não é erro seu. A ferramenta executou, mas não conseguiu fundamentar uma resposta justa, por exemplo wallet/pnl em uma carteira sem negociações precificadas naquele token. Significa que a Cognivo não conseguiu verificar a resposta, não que a resposta seja zero. Você nunca é cobrado por um 422.
• 404 public_api_disabled. A API pública está temporariamente desligada. Isso não é uma URL errada, então tente de novo mais tarde.

Créditos e cobrança

Chaves live são autoatendimento. Não há candidatura nem assinatura. Uma nova chave live funciona imediatamente, e cada chamada bem-sucedida desconta o preço em créditos daquele endpoint do saldo de créditos Cognivo do dono do projeto, os mesmos créditos que o Chat e o dApp usam. Toda conta recebe 5 créditos grátis por dia, renovados à meia-noite UTC. A cobrança das chamadas da Developer API está desligada hoje, então uma chamada bem-sucedida não desconta nada e seu saldo não muda.

O preço em créditos de cada endpoint é exibido ao lado dele na aba Endpoints da página Developers, e os endpoints gratuitos aparecem rotulados como Grátis. Leia o preço no portal em vez de fixá-lo no seu código.

• Chamadas com falha nunca são cobradas. Erros, timeouts, chamadas negadas e limites de taxa não custam nada.
• Uma chamada bem-sucedida é cobrada exatamente uma vez, então retentativas são seguras.
• Resultados honestamente vazios são gratuitos. Um 422, e uma lista wallet/approvals vazia, são respostas válidas e não são cobradas.
• Sem créditos você recebe 402 payment_required sem nada cobrado. Faça uma recarga no dApp e tente de novo.
• Chaves de sandbox (cogv_test_) nunca são cobradas e não conseguem executar inteligência live.
• Chaves suspensas e projetos desativados não conseguem executar nada e nunca são cobrados.
• Enterprise é o caminho de solicitação para preços sob medida, limites personalizados e volume, e você o solicita pelo dApp.

Lendo os resultados com honestidade

Os resultados da API descrevem o que a Cognivo verificou e o que encontrou on-chain. Um resultado limpo não é prova de que um token ou carteira é seguro, e um resultado sinalizado não é prova de fraude. Um campo ausente ou indisponível significa que a Cognivo não conseguiu verificar aquele item, não que não haja nada ali. Trate cada resposta como uma entrada da sua própria pesquisa.

Próximos passos

Consulte parâmetros, escopos e respostas de exemplo na Referência de endpoints, reforce as suas chaves com Autenticação e chaves de API, ou veja como os créditos funcionam no restante do produto em Cobrança e Pacotes de Créditos.