Límites de Velocidad
Los límites de velocidad se aplican por cuenta autenticada, en función de tu clave de API, no por dirección IP. Esto significa que el mismo cliente que accede a la API desde varias máquinas/IPs comparte un solo límite, y diferentes clientes que compartan una IP de salida (detrás de un proxy corporativo, por ejemplo) no se afectan entre sí.
Límites por categoría de endpoint
| Categoría | Límite | Endpoints |
|---|---|---|
| Carga / procesamiento | 30 por minuto | POST /documents, POST /batches/{batch_name}/process, POST /documents/{document_id}/bbox, PUT /batches/{batch_name}/webhook |
| Consulta de estado / resultados | 120 por minuto | GET /documents/{document_id}, GET /batches, GET /batches/{batch_name}, GET /batches/{batch_name}/results, GET /documents/{document_id}/bbox, GET /documents/{document_id}/image, GET /account, GET /account/usage, endpoints de plantillas/campos |
| Exportación | 10 por minuto, 60 por hora | GET /batches/{batch_name}/export |
Estos son los valores predeterminados actuales y pueden ajustarse con el tiempo; las cabeceras de respuesta descritas a continuación siempre reflejan lo que realmente está vigente para el endpoint al que llamaste, así que basa tu implementación en las cabeceras en lugar de codificar estos números de forma fija.
Encabezados de respuesta
Cada respuesta con límite de velocidad — exitosa o no — incluye tres encabezados que indican su estado:
| Encabezado | Significado |
|---|---|
X-RateLimit-Limit | Número total de solicitudes permitidas en la ventana actual. |
X-RateLimit-Remaining | Solicitudes restantes en la ventana actual. |
X-RateLimit-Reset | Momento en que se reinicia la ventana actual. |
Verifique X-RateLimit-Remaining de forma proactiva en un bucle de sondeo y reduzca la velocidad antes de llegar a cero, en lugar de esperar a reaccionar ante un 429.
Cuando supera un límite
Superar un límite devuelve HTTP 429 con la estructura de error estándar v1:
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Demasiadas solicitudes. Reduzca la velocidad y vuelva a intentarlo después de que se reinicie la ventana.",
"doc_url": "https://imagetotable.ai/developers/guides/errors#rate_limit_exceeded"
}
}Si está sondeando el estado de un lote, prefiera registrar un webhook en lugar de un bucle de sondeo intenso — esto elimina el riesgo de alcanzar el límite de sondeo de estado para ese caso de uso.