Créditos
Cada organización tiene un plan que incluye un número mensual de créditos, y cada solicitud consume créditos según lo que cuesta atenderla:
Las solicitudes en lote consumen créditos por elemento: un lote
de 10 solicitudes en vivo consume 100. Los aciertos de caché (
X-Cache: HIT)
consumen lo mismo que un fallo de caché. Las solicitudes fallidas no consumen
nada, y consultar el estado de un job nunca consume créditos.
Los créditos se reinician en la fecha mensual del plan y se administran desde
la consola. Los contratos tienen su
propio número mensual.
Cupos por organización
Los límites de tasa se aplican por organización, no por llave. Cada llave emitida para la misma organización comparte un cupo, así que agregar llaves no lo multiplica. Algunos endpoints tienen un tope por hora adicional sobre el cupo del plan, y la consulta de jobs usa un cupo propio:
Los topes por hora son adicionales, no independientes: una llamada a Research
consume uno de sus 10 espacios por hora y 10 créditos de tu plan.
La página de cada endpoint indica su límite.
Cuota en los encabezados de respuesta
El estado del límite de tasa viene como encabezados HTTP en cada respuesta (no en el cuerpo):Reintentos e idempotencia
Toda operación de Croma es una consulta: repetir una solicitud con el mismo cuerpo devuelve el mismo resultado y nunca crea ni modifica un registro, así que reintentar tras un timeout o una conexión caída siempre es seguro. Envía un encabezado opcionalIdempotency-Key (cualquier cadena de hasta 255
caracteres; un UUID sirve) y la API lo devuelve en el encabezado de respuesta
Idempotency-Key, para que puedas ligar un reintento con su primer intento en
tus logs. Cada intento que llega a la API cuenta contra la cuota de arriba; un
429 te pide esperar Retry-After segundos en lugar de reintentar de
inmediato.
| X-Request-Id | Id único de la solicitud (req_…); inclúyelo en los reportes de soporte. |
| X-Cache | HIT o MISS en endpoints cacheables. Los aciertos de caché igual cuentan contra tu cuota. |
Cuando se agotan los créditos
Una solicitud que tus créditos restantes no cubren devuelve402 con un sobre
billing_error. Mejora el plan desde la consola o espera el reinicio que
indica X-RateLimit-Reset:
Cuando excedes un tope por hora
Las solicitudes que superan un tope por hora devuelven429 con un sobre
rate_limit_error y un encabezado Retry-After (segundos):
Retry-After (o X-RateLimit-Reset),
luego reintenta.
El limitador falla abierto: si el backend de límite de tasa no está
disponible por un momento, las solicitudes se dejan pasar y no se emiten
encabezados
X-RateLimit-*. No dependas de que los encabezados estén siempre
presentes.Siguiente: Errores
El sobre de error y cada código de error.