Límites de uso
Cuántas solicitudes puedes enviar, qué pasa si envías más y otros límites que conviene conocer.
Los límites protegen a todos los que comparten el servicio. Los valores por defecto son generosos para un uso normal; si llegas a uno, la respuesta te dice exactamente cuánto esperar.
De un vistazo
| Límite | Por defecto | Cuando lo alcanzas |
|---|---|---|
Escrituras por cuenta (createTask, retry, subidas…) | 1000 cada 10 segundos | 429 con Retry-After |
Lecturas por cuenta (recordInfo, models, jobs, quote…) | 1000 cada 10 segundos | 429 con Retry-After |
| Tickets de subida | 1000 cada 10 segundos, además de las escrituras | 429 con Retry-After |
Informe de uso (/api/v1/usage) | 30 por minuto y cuenta | 429 con Retry-After |
| Biblioteca de recursos | 60 lecturas y 30 guardados por minuto, más un número diario de recursos nuevos | 429 con Retry-After |
| Cualquier solicitud antes de validar la clave | 6000 por minuto y red | 429 |
| Cuerpo de la solicitud | 2 MiB de JSON | 413 |
| Saldo | Lo que haya en tu cuenta | 40201 |
| Topes de gasto por clave | Ninguno salvo que lo pongas | 40202 |
Los límites cuentan por cuenta, no por clave: crear más claves no los aumenta.
Cabeceras de respuesta
| Cabecera | Significado |
|---|---|
X-RateLimit-Limit | Tu cupo en la ventana actual |
X-RateLimit-Remaining | Lo que te queda; también llega en respuestas correctas, para que frenes a tiempo |
Retry-After | En un 429: segundos que hay que esperar antes de reintentar |
Las cifras de arriba son valores por defecto y pueden cambiar; fíate de las cabeceras en vez de fijarlas en tu código.
Cómo se ve un límite
{ "code": 429, "msg": "Too many requests. Retry in a moment", "request_id": "req_…" }Una solicitud por encima del límite se rechaza al momento —no se pone en cola— y no cuesta nada.
Cómo manejarlo
- Espera al menos
Retry-Aftersegundos y vuelve a intentarlo. Añade algo de aleatoriedad para que un grupo de clientes no vuelva en el mismo instante. - Al reintentar
createTask, envía el mismoIdempotency-Key(Idempotencia). - Sondea con calma: cada pocos segundos para imágenes y cada 10–15 segundos para video. Mejor aún, usa webhooks: no gastan ni una solicitud.
Muchas tareas a la vez
Los límites de uso controlan lo rápido que envías solicitudes, no cuántas tareas se ejecutan a la vez. Puedes tener muchas tareas en marcha; los videos largos simplemente tardan más. Si necesitas lanzar miles de tareas, repártelas en el tiempo y deja que los webhooks te traigan los resultados.
¿Necesitas más cupo para un lanzamiento o un lote grande? Escríbenos con el volumen que esperas.