# Límites de Velocidad de la API — Límites por Cuenta y Cabeceras

> Los límites de velocidad v1 se aplican por cuenta, no por dirección IP, y cada respuesta incluye las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset para que puedas autorregularte antes de recibir un 429.

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:

```json
{
  "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](/developers/guides/webhooks) 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.

---

Source: https://imagetotable.ai/es/developers/guides/rate-limits