Limites de débit, erreurs et facturation

Cette page est la référence pour les trois choses qui empêchent une intégration de fonctionner : épuiser ses requêtes, recevoir une erreur, et manquer de crédits. Elle montre aussi où surveiller ces trois points depuis votre compte.

Consultez-la quand un appel qui fonctionnait hier renvoie un code que vous ne reconnaissez pas, quand vous dimensionnez le nombre de requêtes que votre app peut effectuer, ou quand vous voulez savoir exactement ce qu'un appel coûtera avant de le mettre en production.

Limites de débit

Les limites sont définies par clé, selon le mode d'accès :

Mode d'accès	Limite
payant en direct : basic (par défaut pour toute nouvelle clé en direct)	1 000 requêtes/heure
payant en direct : premium (attribué par un administrateur)	5 000 requêtes/heure
payant en direct : pro (attribué par un administrateur)	15 000 requêtes/heure
partner ou enterprise	configuré par un administrateur
toute clé sandbox cogv_test_	25 requêtes/heure, 100/jour, 1/seconde
surface de métadonnées (health, me, discover) avec toute clé valide	60 requêtes/heure, 1/seconde

Une nouvelle clé en direct démarre en basic sans étape d'approbation. Premium et pro sont attribués par Cognivo, et les limites partner et enterprise sont fixées selon l'accord. Les en-têtes standard RateLimit-* sont renvoyés à chaque appel, ce qui vous permet de voir votre budget restant sans deviner. Quand le budget est épuisé, vous obtenez 429 rate_limited avec un en-tête Retry-After qui indique quand réessayer.

Surveiller votre usage

Connectez-vous à la dApp, ouvrez Account dans la barre latérale gauche, choisissez Developers, puis ouvrez l'onglet Usage.

L'onglet Usage de la page Developers, tel qu'il apparaît pour une clé qui n'a pas encore servi.Agrandir l'image

Le sélecteur de fenêtre en haut bascule entre Last 24 hours, Last 7 days et Last 30 days. À côté, une puce affiche votre solde de crédits et une autre le palier de débit et la limite horaire qui s'appliquent à vos clés. En dessous, cinq compteurs découpent la fenêtre en Requests, Successful, Errors, Rate limited et Credits used, et la carte Outcome breakdown répartit la même fenêtre en trois.

Quoted vs charged est le panneau à lire avant de vous inquiéter d'une facture. Selon les mots du produit lui-même, « Quoted is the list price. Charged is what actually came out of your balance. » Les deux chiffres ne sont pas toujours identiques, car les appels en échec, les appels refusés et les réponses honnêtement vides sont annoncés mais jamais facturés.

Request history liste les appels individuels et peut être filtré par clé, endpoint et statut. Deux états vides ont des significations différentes. « No requests match these filters. » signifie que des appels existent dans cette fenêtre mais qu'aucun ne correspond à votre filtre, alors élargissez les filtres. « No usage in this window yet. » signifie qu'aucun appel d'aucune de vos clés n'est arrivé dans cette fenêtre. Ni l'un ni l'autre n'est une erreur, et ni l'un ni l'autre ne signifie qu'un appel a été perdu. Si vous attendiez du trafic et voyez zéro, vérifiez que votre app utilise bien la clé que vous croyez, et élargissez la fenêtre.

Codes d'erreur

HTTP	error	Signification
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	Entrée mal formée. chain doit être eth, base ou bsc, et les adresses doivent être 0x suivi de 40 caractères hexadécimaux.
401	missing_api_key	Aucun X-API-Key ni jeton Bearer présenté.
401	invalid_api_key	Clé inconnue, ou pas une clé Cognivo v2.
402	payment_required	Pas assez de crédits Cognivo pour cet appel. Rien n'a été facturé.
403	access_required	Une ancienne clé limitée aux métadonnées a tenté un appel en direct.
403	sandbox_limited	Une clé sandbox (cogv_test_) a tenté un appel d'intelligence en direct.
403	trial_expired	L'allocation d'essai facultative de la clé a expiré.
403	trial_exhausted	L'allocation d'essai facultative de la clé est entièrement consommée.
403	endpoint_denied	L'accord d'accès de la clé ne couvre pas cet endpoint.
403	chain_denied	La clé est restreinte à certains réseaux et cette requête en a nommé un autre. Refusé avant tout appel en amont et avant l'utilisation de toute allocation.
403	key_expired	L'expiration de la clé est dépassée. Elle est refusée partout, y compris sur GET /v1/api/me.
403	suspended_key	La clé est suspendue et ne peut pas s'exécuter. Le portail en affiche la raison.
403	revoked_api_key	La clé a été révoquée ou remplacée par rotation.
403	project_disabled	Le projet propriétaire est suspendu ou archivé.
403	scope_denied	La clé ne dispose pas de la portée dont cet endpoint a besoin.
403	origin_denied	Une liste d'autorisation d'origines ou d'IP est configurée sur la clé et cette requête n'y correspondait pas.
404	public_api_disabled	L'API publique est temporairement désactivée.
422	insufficient_data et similaires	L'outil s'est exécuté mais n'a pas pu fonder un résultat honnête. Vous n'êtes pas facturé.
429	rate_limited	Budget de débit épuisé. La réponse porte Retry-After.
500	internal_error	Échec inattendu. Incluez request_id quand vous contactez le support.
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	Un rare incident de facturation ou de dépendance. Rien n'a été facturé, alors réessayez.

Chaque réponse porte un request_id, et les réponses réussies le répètent dans meta.request_id. Conservez-le. Le support peut retracer un appel précis à partir de cette seule valeur.

Erreurs courantes et comment les corriger

• 401 missing_api_key. La clé ne nous est jamais parvenue. Envoyez-la dans l'en-tête X-API-Key, orthographié exactement, ou sous la forme Authorization: Bearer YOUR_API_KEY, et vérifiez qu'aucun proxy ne supprime l'en-tête.
• 401 invalid_api_key. La clé doit commencer par cogv_live_ ou cogv_test_. Copiez la clé entière sans espaces autour. Si vous avez perdu l'original, faites tourner la clé dans le portail et utilisez la nouvelle.
• 402 payment_required. Rechargez sur votre page de facturation Cognivo, puis réessayez. Rien n'a été facturé. GET /v1/api/me affiche votre solde actuel.
• 403 revoked_api_key. Prenez la clé la plus récente dans le portail. L'ancienne ne fonctionnera plus jamais.
• 403 scope_denied. La clé fonctionne mais n'a pas la portée dont cet endpoint a besoin, par exemple security:read pour wallet/approvals. Voir Authentification et clés d'API.
• 403 origin_denied. Appelez depuis une origine ou une IP autorisée, ou videz les listes sur la clé.
• 403 access_required. Il s'agit d'une ancienne clé limitée aux métadonnées, antérieure à la facturation en libre-service. Créez une nouvelle clé en direct dans le portail.
• 403 sandbox_limited. Les clés sandbox servent aux tests et ne peuvent pas exécuter d'intelligence en direct. Créez une clé en direct.
• 403 chain_denied. Vérifiez allowed_chains sur GET /v1/api/me. Un null signifie aucune restriction. Rien n'a été facturé.
• 403 trial_expired ou trial_exhausted. L'allocation d'évaluation facultative est terminée. Vous n'avez pas besoin d'un essai, alors passez à une clé en direct ordinaire.
• 403 endpoint_denied. Votre accord couvre d'autres endpoints mais pas celui-ci. Demandez à l'y inclure.
• 403 suspended_key. Le portail en affiche la raison. Contactez le support depuis la dApp avec votre request_id si ce n'est pas clair.
• 429 rate_limited. Respectez l'en-tête Retry-After et ajoutez une file d'attente côté client avec temporisation progressive, ou demandez une limite plus élevée.
• 400 invalid_chain. Utilisez eth, base ou bsc. Les noms comme ethereum et les identifiants de chaîne numériques ne sont pas acceptés.
• 400 invalid_address, invalid_wallet, invalid_token. Envoyez une adresse complète 0x suivie de 40 caractères hexadécimaux. L'API ne résout pas les noms ENS ni les symboles de tokens.
• 422 insufficient_data. Ce n'est ni une panne ni votre erreur. L'outil s'est exécuté mais n'a pas pu fonder une réponse honnête, par exemple wallet/pnl sur un wallet sans transactions valorisées dans ce token. Cela signifie que Cognivo n'a pas pu vérifier la réponse, pas que la réponse est nulle. Vous n'êtes jamais facturé pour un 422.
• 404 public_api_disabled. L'API publique est temporairement désactivée. Ce n'est pas une mauvaise URL, alors réessayez plus tard.

Crédits et facturation

Les clés en direct sont en libre-service. Il n'y a ni candidature ni abonnement. Une nouvelle clé en direct fonctionne immédiatement, et chaque appel réussi déduit le prix en crédits de cet endpoint du solde de crédits Cognivo du propriétaire du projet, les mêmes crédits qu'utilisent Chat et la dApp. Chaque compte reçoit 5 crédits gratuits par jour, réinitialisés à minuit UTC. La facturation des appels à la Developer API est désactivée aujourd'hui : un appel réussi ne déduit rien et votre solde ne bouge pas.

Le prix en crédits de chaque endpoint est indiqué à côté de lui dans l'onglet Endpoints de la page Developers, et les endpoints gratuits y sont étiquetés Free. Lisez le prix depuis le portail plutôt que de le coder en dur.

• Les appels en échec ne sont jamais facturés. Les erreurs, les délais dépassés, les appels refusés et les limites de débit ne coûtent rien.
• Un appel réussi est facturé exactement une fois, donc les nouvelles tentatives sont sans danger.
• Les résultats honnêtement vides sont gratuits. Un 422, et une liste wallet/approvals vide, sont des réponses valides et ne sont pas facturées.
• À court de crédits, vous obtenez 402 payment_required sans rien facturer. Rechargez dans la dApp, puis réessayez.
• Les clés sandbox (cogv_test_) ne sont jamais facturées et ne peuvent pas exécuter d'intelligence en direct.
• Les clés suspendues et les projets désactivés ne peuvent rien exécuter et ne sont jamais facturés.
• Enterprise est le chemin de demande pour des tarifs sur mesure, des limites personnalisées et du volume, et vous en faites la demande depuis la dApp.

Lire les résultats honnêtement

Les résultats de l'API décrivent ce que Cognivo a vérifié et ce qu'il a trouvé on-chain. Un résultat propre n'est pas la preuve qu'un token ou un wallet est sûr, et un résultat signalé n'est pas la preuve d'une fraude. Un champ manquant ou indisponible signifie que Cognivo n'a pas pu vérifier cet élément, et non qu'il n'y a rien. Traitez chaque réponse comme un élément parmi d'autres de vos propres recherches.

Étapes suivantes

Retrouvez les paramètres, les portées et des exemples de réponses dans la Référence des endpoints, renforcez vos clés avec Authentification et clés d'API, ou découvrez le fonctionnement des crédits dans le reste du produit avec Facturation et crédits.