Limites de débit, erreurs et facturation

Limites de débit

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

Mode d'accès	Limite
free (métadonnées : `health`, `me`, `discover`)	60 requêtes/heure, avec un plafond de rafale de 1/seconde
basic (payant, une fois lancé)	1 000 requêtes/heure
premium (payant, une fois lancé)	5 000 requêtes/heure
pro (payant, une fois lancé)	15 000 requêtes/heure
partenaire / enterprise	configuré par un administrateur
toute clé sandbox `cogv_test_`	25 requêtes/heure et 100/jour

Les nouvelles clés démarrent avec le seul accès gratuit aux métadonnées. L'accès trial est accordé par un administrateur, limité et à durée déterminée ; les limites partenaire et enterprise sont configurées selon l'accord - demandez l'accès depuis la dApp. Les en-têtes standard RateLimit-* sont renvoyés ; en cas d'épuisement, vous obtenez 429 rate_limited.

Codes d'erreur

HTTP	`error`	Signification
400	`bad_request` / `invalid_chain` / `invalid_address` / `invalid_wallet` / `invalid_token`	entrée malformée ; la chaîne doit être `eth`, `base` ou `bsc` ; les adresses doivent être `0x` + 40 hex
401	`missing_api_key`	aucun `X-API-Key` (ni Bearer) présenté
401	`invalid_api_key`	clé inconnue ou qui n'est pas une clé v2 Cognivo
402	`insufficient_credits`	usage payant : votre solde de crédits Cognivo ne peut pas couvrir l'appel (rien n'a été facturé)
402	`payment_required`	cet endpoint nécessite un accès payant sur cette clé et aucune voie de paiement valide ne couvre l'appel (rien n'a été facturé)
403	`access_required`	la clé n'a aucun droit d'accès aux endpoints d'intelligence en direct - demandez un accès trial, partenaire, payant ou enterprise
403	`sandbox_limited`	une clé sandbox (`cogv_test_`) a tenté un appel en direct hors de son allocation de démo activée par un administrateur
403	`trial_expired`	l'accès trial de la clé a expiré
403	`trial_exhausted`	l'allocation trial de la clé est entièrement consommée
403	`endpoint_denied`	le droit d'accès de la clé ne couvre pas cet endpoint spécifique
403	`suspended_key`	la clé a été suspendue par un administrateur
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é n'a pas le scope dont cet endpoint a besoin
403	`origin_denied`	une liste d'autorisation Origin/IP est configurée sur la clé et ne correspond 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 horaire du palier épuisé
500	`internal_error`	échec inattendu - incluez le `request_id` en contactant le support
503	`billing_unavailable` / `unavailable`	panne temporaire d'une dépendance - réessayez plus tard, rien n'est facturé

Chaque réponse porte un request_id (aussi meta.request_id en cas de succès). Conservez-le ; le support peut retracer un appel à partir de lui.

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 (nom exact) ou comme Authorization: Bearer YOUR_API_KEY, et vérifiez qu'un proxy ou un framework ne supprime pas l'en-tête.
401 invalid_api_key - la clé n'est pas reconnue. Elle doit commencer par cogv_live_ ou cogv_test_ ; vérifiez que vous avez copié la clé entière sans espaces autour. Si vous avez perdu l'originale, effectuez une rotation dans le portail et utilisez la nouvelle.
403 revoked_api_key - cette clé a été révoquée ou remplacée par rotation. Récupérez la clé la plus récente dans le portail ; l'ancienne ne fonctionnera plus jamais.
403 scope_denied - la clé fonctionne, mais elle n'a pas le scope dont cet endpoint a besoin (par exemple security:read pour wallet/approvals). Modifiez les scopes de la clé ou créez une clé avec le bon scope ; voir Authentification et clés d'API.
403 origin_denied - la clé a une liste d'autorisation d'Origin ou d'IP et cette requête venait d'ailleurs. Appelez depuis une origine/IP autorisée, ou videz les listes de la clé.
403 access_required - la clé est valide mais n'a aucun droit d'accès aux endpoints d'intelligence en direct. Demandez un accès trial, partenaire, payant ou enterprise depuis le portail développeur ; sans lui, l'appel ne s'exécute jamais (et ne facture jamais).
403 sandbox_limited - une clé sandbox (cogv_test_) a tenté un appel d'intelligence en direct hors de son allocation de démo. Demandez à un administrateur d'activer l'allocation de démo en direct pour la clé, ou utilisez une clé live avec un accès.
403 trial_expired / trial_exhausted - votre trial est terminé (durée ou allocation). Demandez une prolongation ou passez à un accès payant, partenaire ou enterprise.
403 endpoint_denied - votre droit d'accès couvre d'autres endpoints mais pas celui-ci (l'accès spécifique par endpoint est courant sur les droits partenaire/enterprise). Demandez l'accès à cet endpoint.
403 suspended_key - la clé a été suspendue par un administrateur. Contactez le support depuis la dApp avec votre request_id.
402 payment_required - cet appel nécessite un accès payant sur cette clé. Rechargez des crédits Cognivo ou demandez un mode d'accès qui couvre l'endpoint ; rien n'a été facturé.
429 rate_limited - vous avez épuisé le budget de cette clé. Ralentissez, ajoutez une mise en file d'attente côté client avec backoff, ou demandez un mode d'accès supérieur. Rappelez-vous que les clés sandbox cogv_test_ sont plafonnées à 25 requêtes/heure et 100/jour ; l'accès gratuit aux métadonnées est plafonné à 60/heure avec un plafond de rafale de 1/seconde.
400 invalid_chain - chain doit être eth, base ou bsc. Les noms comme ethereum ou les identifiants numériques de chaîne comme 8453 ne sont pas acceptés.
400 invalid_address / invalid_wallet / invalid_token - envoyez une adresse complète 0x + 40 caractères hexadécimaux. Les noms ENS et les symboles de tokens ne sont pas résolus par l'API.
422 insufficient_data - ce n'est ni une panne ni votre faute : 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 transaction valorisée sur ce token). Vous n'êtes jamais facturé pour un 422 ; essayez un autre wallet/token ou une question plus large.
404 public_api_disabled - l'API publique est temporairement désactivée, ce n'est pas une mauvaise URL. Réessayez plus tard ou consultez le canal d'annonces.

Accès, facturation et crédits

La Developer API est à accès contrôlé pendant l'accès anticipé. Une clé gratuite peut explorer : lire la documentation, appeler GET /v1/api/health, s'inspecter elle-même avec GET /v1/api/me et effectuer des appels sandbox/démo limités. Les endpoints d'intelligence en direct nécessitent un accès trial, partenaire, payant ou enterprise ; sans lui, ils renvoient une erreur claire (access_required, trial_expired, payment_required et similaires) au lieu de s'exécuter gratuitement.

L'usage payant est facturé en crédits Cognivo par appel réussi, depuis votre solde de crédits Cognivo existant (les mêmes crédits que Chat/Telegram), dépensés par le compte du propriétaire du projet. Les échecs, timeouts, résultats vides et erreurs ne sont pas facturés.
Les débits sont idempotents - une requête réessayée ou dupliquée ne peut pas être facturée deux fois.
Les clés sandbox (cogv_test_) servent aux tests d'intégration : plafonnées à 25 requêtes/heure et 100/jour, elles ne peuvent exécuter qu'une petite allocation de démo en direct quand un administrateur l'active.
L'accès trial est accordé par un administrateur, limité et à durée déterminée.
Enterprise est sur mesure : tarifs, limites plus élevées et accès spécifique par endpoint - demandez l'accès depuis la dApp.

Coûts en crédits par endpoint (ils s'appliquent à l'usage payant ; affichés par souci de transparence) :

Endpoint	Crédits par appel réussi
`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`	gratuit
`discover`	gratuit, avec un plafond de débit strict

Pas des conseils financiers

Les résultats de l'API sont des signaux d'intelligence on-chain, pas des conseils d'investissement, et l'absence de drapeau rouge n'est pas une preuve de sécurité. Faites toujours vos propres recherches.