API · Referencia
Límites de solicitudes
Límites de solicitudes de la API de Clipia — 120 solicitudes por minuto por clave y 600 por cuenta, cabeceras RateLimit-*, la respuesta 429, límites de concurrencia y límites de LLM.
Las solicitudes a la API están limitadas por dos contadores: 120 solicitudes por minuto por clave y 600 solicitudes por minuto por cuenta entre todas sus claves. La ventana es un minuto natural: los contadores se reinician al comienzo de cada minuto. Superar cualquiera de los dos rechaza la solicitud con 429 rate_limit_exceeded.
Límites por defecto
| Límite | Valor | Respuesta al superarlo |
|---|---|---|
| Solicitudes por minuto por clave | 120 | 429 rate_limit_exceeded |
| Solicitudes por minuto por cuenta | 600 entre todas las claves | 429 rate_limit_exceeded |
| Generaciones simultáneas | ilimitadas | — |
El equipo de Clipia configura límites personalizados por clave previa solicitud; no se pueden cambiar en la Developer Console.
Cabeceras de respuesta
Cada respuesta a una solicitud con clave incluye las cabeceras del límite por clave:
Prop
Type
El límite de la cuenta no aparece en las cabeceras
RateLimit-Remaining cuenta solo las solicitudes de la clave actual. Si varias claves de una misma cuenta superan juntas las 600 solicitudes por minuto, recibirá 429 aunque una clave concreta aún tenga margen.
La respuesta 429
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 1760011260
Retry-After: 37{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "API rate limit exceeded. Slow down and retry after the reset window."
}
}Espere el número de segundos indicado en Retry-After y reintente. Es más fiable que un retraso fijo. Si falta Retry-After, calcule la pausa como RateLimit-Reset menos la hora Unix actual.
Generaciones simultáneas
Por defecto, el número de generaciones simultáneas es ilimitado. Si hay un límite configurado para la clave o la cuenta, un envío que lo supere devuelve 429 con:
{
"error": {
"type": "api_error",
"code": "concurrency_limit_exceeded",
"message": "Too many concurrent generations in flight (limit 5). Wait for one to finish, then retry."
}
}Espere a que termine uno de sus trabajos y reintente. Una plaza se libera cuando termina su trabajo; una plaza bloqueada se libera automáticamente al cabo de 30 minutos. Cuando hay un límite configurado y el control de concurrencia no está disponible temporalmente, el envío devuelve 503 service_unavailable: reintente en unos segundos.
El límite de concurrencia se aplica a los envíos de generaciones y al chat con LLM. Las consultas de estado y de resultado no cuentan.
Límites de las claves de LLM
Para una clave que se usa con AI Gateway, el equipo de Clipia puede configurar límites adicionales:
| Límite | Respuesta al superarlo |
|---|---|
| Tokens de LLM por minuto | 429 rate_limit_exceeded, con las cabeceras x-ratelimit-remaining-tokens y x-ratelimit-limit-tokens |
| Presupuesto de créditos por periodo | 402 insufficient_quota |
Estos límites no están configurados por defecto.
Webhooks
Una notificación POST a su servidor cuando termina una generación — formato del cuerpo, verificación de la firma HMAC-SHA256, plazo de respuesta y calendario de reintentos de entrega.
Errores
El formato único de errores de la API de Clipia — campos type, code y message, la tabla de estados HTTP y códigos, qué reintentar y cómo leer message.