Límites de tasa, errores y facturación

Límites de tasa

Los límites son por clave, según el modo de acceso:

Modo de acceso	Límite
live de pago: basic (por defecto para toda clave live nueva)	1,000 solicitudes/hora
live de pago: premium (asignado por un administrador)	5,000 solicitudes/hora
live de pago: pro (asignado por un administrador)	15,000 solicitudes/hora
partner / enterprise	configurado por un administrador
cualquier clave sandbox cogv_test_	25 solicitudes/hora, 100/día, 1/segundo
superficie de metadatos (health, me, discover) con cualquier clave válida	60 solicitudes/hora, 1/segundo

Una clave live nueva comienza en basic (1,000 solicitudes/hora) sin paso de aprobación; premium y pro los asigna un administrador, y los límites de partner y enterprise se configuran según el acuerdo. Se devuelven los encabezados estándar RateLimit-*; al agotar el límite obtienes 429 rate_limited con un encabezado Retry-After que te dice cuándo volver a intentarlo.

Códigos de error

HTTP	error	Significado
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	entrada malformada; la cadena debe ser eth, base o bsc; las direcciones deben ser 0x + 40 hex
401	missing_api_key	no se presentó X-API-Key (ni Bearer)
401	invalid_api_key	clave desconocida o que no es una clave v2 de Cognivo
402	payment_required	no hay suficientes créditos de Cognivo para esta llamada. Recarga en la página de facturación de tu cuenta de Cognivo e inténtalo de nuevo. No se cobró nada; las llamadas fallidas nunca se cobran
403	access_required	una clave heredada solo de metadatos intentó una llamada en vivo - crea una clave live de autoservicio nueva para pasar al pago por uso
403	sandbox_limited	una clave Sandbox (cogv_test_) intentó una llamada de inteligencia en vivo; las claves sandbox no pueden ejecutar inteligencia en vivo
403	trial_expired	la asignación trial opcional de la clave ha expirado
403	trial_exhausted	la asignación trial opcional de la clave está totalmente consumida
403	endpoint_denied	el acuerdo de acceso de la clave no cubre este endpoint específico
403	suspended_key	la clave está suspendida y no puede ejecutar; el portal muestra el motivo
403	revoked_api_key	la clave fue revocada o reemplazada por rotación
403	project_disabled	el proyecto propietario está suspendido o archivado
403	scope_denied	la clave carece del scope que este endpoint necesita
403	origin_denied	hay una lista de permitidos de Origin/IP configurada en la clave y no hubo coincidencia
404	public_api_disabled	la API pública está temporalmente apagada
422	insufficient_data (y similares)	la herramienta se ejecutó pero no pudo fundamentar un resultado justo - no se te cobra
429	rate_limited	presupuesto de tasa agotado; la respuesta lleva Retry-After
500	internal_error	fallo inesperado - incluye el request_id al contactar a soporte
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	contratiempo raro de facturación o de una dependencia - no se cobró nada, simplemente reintenta

Toda respuesta lleva request_id (también meta.request_id en caso de éxito). Consérvalo; soporte puede rastrear una llamada a partir de él.

Errores comunes y cómo solucionarlos

• 401 missing_api_key - la clave nunca nos llegó. Envíala en el encabezado X-API-Key (nombre exacto) o como Authorization: Bearer YOUR_API_KEY, y verifica que un proxy o framework no esté eliminando el encabezado.
• 401 invalid_api_key - la clave no se reconoce. Debe comenzar con cogv_live_ o cogv_test_; verifica que copiaste la clave completa sin espacios alrededor. Si perdiste la original, rota la clave en el portal y usa la nueva.
• 402 payment_required - no hay suficientes créditos de Cognivo para esta llamada. Recarga en la página de facturación de tu cuenta de Cognivo e inténtalo de nuevo; no se cobró nada, y las llamadas fallidas nunca se cobran. GET /v1/api/me muestra tu saldo actual.
• 403 revoked_api_key - esta clave fue revocada o reemplazada por rotación. Toma la clave más reciente del portal; la antigua nunca volverá a funcionar.
• 403 scope_denied - la clave funciona, pero carece del scope que este endpoint necesita (por ejemplo security:read para wallet/approvals). Edita los scopes de la clave o crea una clave con el scope correcto; ver Autenticación y claves de API.
• 403 origin_denied - la clave tiene una lista de permitidos de Origin o IP y esta solicitud vino de otro lugar. Llama desde un origen/IP en la lista de permitidos, o vacía las listas de la clave.
• 403 access_required - esta es una clave heredada solo de metadatos, anterior a la facturación de autoservicio. Crea una clave live nueva en el portal; funciona de inmediato, con pago por uso y sin paso de aprobación.
• 403 sandbox_limited - una clave Sandbox (cogv_test_) intentó una llamada de inteligencia en vivo. Las claves sandbox son solo para demos y pruebas limitadas; crea una clave live, que funciona de inmediato.
• 403 trial_expired / trial_exhausted - tu asignación de evaluación opcional ha terminado (por tiempo o por uso). No necesitas un trial: pasa a una clave live ordinaria con pago por uso, o pregunta por enterprise para volumen.
• 403 endpoint_denied - tu acuerdo de acceso cubre otros endpoints pero no este (el acceso específico por endpoint es común en acuerdos partner/enterprise). Solicita que este endpoint sea incluido.
• 403 suspended_key - la clave está suspendida y no puede ejecutar. El portal muestra el motivo; contacta a soporte desde la dApp con tu request_id si no está claro.
• 429 rate_limited - agotaste el presupuesto de esta clave. Respeta el encabezado Retry-After, agrega encolado con backoff del lado del cliente, o pregunta por un límite mayor. Recuerda que las claves sandbox cogv_test_ están topadas a 25 solicitudes/hora, 100/día y 1/segundo; la superficie de metadatos está topada a 60/hora con un tope de ráfaga de 1/segundo.
• 400 invalid_chain - chain debe ser eth, base o bsc. Nombres como ethereum o ids numéricos de cadena como 8453 no se aceptan.
• 400 invalid_address / invalid_wallet / invalid_token - envía una dirección completa 0x + 40 caracteres hexadecimales. La API no resuelve nombres ENS ni símbolos de tokens.
• 422 insufficient_data - no es una caída ni es tu culpa: la herramienta se ejecutó pero no pudo fundamentar una respuesta justa (por ejemplo wallet/pnl en una billetera sin operaciones con precio en ese token). Nunca se te cobra por un 422; prueba con otra billetera/token o una pregunta más amplia.
• 503 pricing_mismatch / billing_unavailable / billing_commit_failed - un contratiempo raro de facturación. No se cobró nada; simplemente reintenta la llamada.
• 404 public_api_disabled - la API pública está temporalmente apagada, no es una URL incorrecta. Intenta más tarde o revisa el canal de anuncios.

Facturación, créditos y recargas

Las claves live son de autoservicio y de pago por uso. No hay solicitud, no se requiere trial y no hay suscripción: una clave live nueva funciona de inmediato y cada llamada exitosa deduce el precio en créditos del endpoint del saldo de créditos de Cognivo del propietario del proyecto (los mismos créditos de Chat y la dApp).

• Las llamadas fallidas nunca se cobran. Los errores, timeouts, llamadas denegadas y límites de tasa no cuestan nada.
• Una llamada exitosa se cobra exactamente una vez. Los envíos duplicados de la misma operación no pueden cobrarte dos veces, así que reintentar es seguro.
• Los resultados vacíos honestos son gratis. Un 422 (por ejemplo wallet/pnl sin operaciones con precio) y una lista vacía de wallet/approvals son respuestas válidas y no se cobran.
• ¿Sin créditos? Obtienes 402 payment_required y no se cobra nada. Recarga en la página de facturación de tu cuenta de Cognivo en la dApp y luego reintenta. GET /v1/api/me muestra tu credits_balance y la guía top_up.
• Las claves Sandbox (cogv_test_) nunca se cobran: son para demos limitadas y pruebas de integración y no pueden ejecutar inteligencia en vivo.
• Trial es una asignación de evaluación opcional otorgada por un administrador - no se necesita para el uso de pago ordinario. Partner es gestionado por un administrador. Enterprise es la vía de solicitud para precios a medida, límites a medida y volumen - solicítalo desde la dApp.
• Las claves suspendidas y los proyectos deshabilitados no pueden ejecutar nada y nunca se cobran; el portal muestra el motivo.

Precios en créditos por llamada exitosa:

Endpoint	Créditos por llamada exitosa
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	gratis
discover	gratis, con un tope de tasa estricto

No es asesoramiento financiero

Los resultados de la API son señales de inteligencia on-chain, no asesoramiento de inversión, y la ausencia de una bandera roja no es prueba de seguridad. Siempre haz tu propia investigación.