Límites de tasa, errores y facturación

Esta página es la referencia de las tres cosas que hacen que una integración deje de funcionar: quedarse sin solicitudes, recibir un error y quedarse sin créditos. También muestra desde dónde vigilar las tres en tu cuenta.

Recurre a ella cuando una llamada que funcionaba ayer devuelva un código que no reconoces, cuando estés dimensionando cuántas solicitudes puede hacer tu app, o cuando quieras saber exactamente cuánto costará una llamada antes de publicarla.

Límites de tasa

Los límites se establecen 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 o 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 sin paso de aprobación. Premium y pro los asigna Cognivo, y los límites de partner y enterprise se establecen según el acuerdo. Los encabezados estándar RateLimit-* vuelven en cada llamada, así que puedes ver tu presupuesto restante sin adivinar. Cuando el presupuesto se agota, obtienes 429 rate_limited con un encabezado Retry-After que te dice cuándo volver a intentarlo.

Vigilar tu uso

Inicia sesión en la dApp, abre Account en la barra lateral izquierda, elige Developers y abre la pestaña Usage.

La pestaña Usage de la página Developers, tal como se ve con una clave que todavía no se ha usado.Ampliar imagen

El selector de ventana en la parte superior alterna entre Last 24 hours, Last 7 days y Last 30 days. Junto a él, una etiqueta muestra tu saldo de créditos y otra muestra el nivel de tasa y el límite por hora que aplica a tus claves. Debajo, cinco contadores desglosan la ventana en Requests, Successful, Errors, Rate limited y Credits used, y la tarjeta Outcome breakdown divide esa misma ventana de tres formas.

Quoted vs charged es el panel que hay que leer antes de preocuparse por una factura. En las propias palabras del producto: "Quoted is the list price. Charged is what actually came out of your balance." Los dos números no siempre coinciden, porque las llamadas fallidas, las denegadas y las respuestas honestamente vacías se cotizan pero nunca se cobran.

Request history lista llamadas individuales y puede filtrarse por clave, endpoint y estado. Dos estados vacíos significan cosas distintas. "No requests match these filters." significa que hay llamadas en esta ventana pero ninguna coincide con lo que filtraste, así que amplía los filtros. "No usage in this window yet." significa que ninguna llamada de ninguna de tus claves cayó en esta ventana. Ninguno de los dos es un error, y ninguno significa que se haya perdido una llamada. Si esperabas tráfico y ves cero, comprueba que tu app esté usando la clave que crees y amplía la ventana.

Códigos de error

HTTP	error	Significado
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	Entrada malformada. chain debe ser eth, base o bsc, y las direcciones deben ser 0x más 40 caracteres hexadecimales.
401	missing_api_key	No se presentó X-API-Key ni token 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. No se cobró nada.
403	access_required	Una clave heredada solo de metadatos intentó una llamada en vivo.
403	sandbox_limited	Una clave sandbox (cogv_test_) intentó una llamada de 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.
403	chain_denied	La clave está restringida a ciertas redes y esta solicitud nombró otra distinta. Rechazada antes de cualquier llamada aguas arriba y antes de usar ninguna asignación.
403	key_expired	La expiración de la clave ya pasó. Se rechaza en todas partes, incluido GET /v1/api/me.
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 o IP configurada en la clave y esta solicitud no coincidió con ella.
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	Un contratiempo raro de facturación o de una dependencia. No se cobró nada, así que reintenta.

Cada respuesta lleva request_id, y las respuestas exitosas lo repiten como meta.request_id. Consérvalo. Soporte puede rastrear una llamada concreta a partir de ese único valor.

Errores comunes y cómo solucionarlos

• 401 missing_api_key. La clave nunca nos llegó. Envíala en el encabezado X-API-Key, escrito exactamente así, o como Authorization: Bearer YOUR_API_KEY, y comprueba que ningún proxy esté eliminando el encabezado.
• 401 invalid_api_key. La clave debe comenzar con cogv_live_ o cogv_test_. Copia la clave completa sin espacios alrededor. Si perdiste la original, rota la clave en el portal y usa la nueva.
• 402 payment_required. Recarga en tu página de facturación de Cognivo y luego reintenta. No se cobró nada. GET /v1/api/me muestra tu saldo actual.
• 403 revoked_api_key. 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. Consulta Autenticación y claves de API.
• 403 origin_denied. Llama desde un origen o 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.
• 403 sandbox_limited. Las claves sandbox son para pruebas y no pueden ejecutar inteligencia en vivo. Crea una clave live.
• 403 chain_denied. Revisa allowed_chains en GET /v1/api/me. Un null ahí significa sin restricción. No se cobró nada.
• 403 trial_expired o trial_exhausted. La asignación de evaluación opcional ha terminado. No necesitas un trial, así que pasa a una clave live ordinaria.
• 403 endpoint_denied. Tu acuerdo cubre otros endpoints pero no este. Pide que se incluya.
• 403 suspended_key. El portal muestra el motivo. Contacta a soporte desde la dApp con tu request_id si no queda claro.
• 429 rate_limited. Respeta el encabezado Retry-After y añade una cola con retroceso en el cliente, o consulta por un límite más alto.
• 400 invalid_chain. Usa eth, base o bsc. Nombres como ethereum y los identificadores numéricos de cadena no se aceptan.
• 400 invalid_address, invalid_wallet, invalid_token. Envía una dirección completa 0x más 40 caracteres hexadecimales. La API no resuelve nombres ENS ni símbolos de tokens.
• 422 insufficient_data. No es una caída del servicio ni un error tuyo. La herramienta se ejecutó pero no pudo fundamentar una respuesta justa, por ejemplo wallet/pnl sobre una billetera sin operaciones con precio en ese token. Significa que Cognivo no pudo verificar la respuesta, no que la respuesta sea cero. Un 422 nunca se te cobra.
• 404 public_api_disabled. La API pública está temporalmente apagada. No es una URL equivocada, así que inténtalo más tarde.

Créditos y facturación

Las claves live son de autoservicio. No hay solicitud ni suscripción. Una clave live nueva funciona de inmediato, y cada llamada exitosa descuenta el precio en créditos de ese endpoint del saldo de créditos de Cognivo del propietario del proyecto, los mismos créditos que usan Chat y la dApp. Cada cuenta recibe 5 créditos gratis al día, y se reinician a medianoche UTC. El cobro por las llamadas a la Developer API está desactivado hoy, así que una llamada exitosa no descuenta nada y tu saldo no cambia.

El precio en créditos de cada endpoint está impreso junto a él en la pestaña Endpoints de la página de Developers, y los endpoints gratis están etiquetados ahí como Free. Lee el precio desde el portal en lugar de fijarlo en el código.

• Las llamadas fallidas nunca se cobran. Los errores, los tiempos de espera agotados, las llamadas denegadas y los límites de tasa no cuestan nada.
• Una llamada exitosa se cobra exactamente una vez, así que los reintentos son seguros.
• Los resultados honestamente vacíos son gratis. Un 422, y una lista vacía de wallet/approvals, son respuestas válidas y no se cobran.
• Quedarse sin créditos te da 402 payment_required sin que se cobre nada. Recarga en la dApp y luego reintenta.
• Las claves sandbox (cogv_test_) nunca se cobran y no pueden ejecutar inteligencia en vivo.
• Las claves suspendidas y los proyectos deshabilitados no pueden ejecutar nada y nunca se cobran.
• Enterprise es la vía de solicitud para precios a medida, límites a medida y volumen, y la solicitas desde la dApp.

Leer los resultados con honestidad

Los resultados de la API describen lo que Cognivo verificó y lo que encontró en la cadena. Un resultado limpio no es prueba de que un token o una billetera sean seguros, y un resultado marcado no es prueba de fraude. Un campo ausente o no disponible significa que Cognivo no pudo verificar ese elemento, no que no haya nada ahí. Trata cada respuesta como una entrada más para tu propia investigación.

Siguientes pasos

Consulta parámetros, scopes y respuestas de ejemplo en la Referencia de endpoints, refuerza tus claves con Autenticación y claves de API, o mira cómo funcionan los créditos en el resto del producto en Facturación y créditos.