Límites
El API limita las solicitudes por minuto por token, por empresa y por dirección IP. Las respuestas con un token válido y las de las rutas públicas informan cuántas quedan, y al superar un límite la respuesta es 429 con el tiempo de espera.
Límites por minuto
| Límite | Valor | Operaciones |
|---|---|---|
| General por token | 60 solicitudes por minuto | Todas las que requieren token |
| Emisiones por token | 20 por minuto | Emitir factura, nota de crédito y retención, y reprocesar |
| Emisiones por empresa | 40 por minuto, sumando todos sus tokens | Las mismas |
| Correo por token | 10 por minuto | Reenviar el correo |
| RUC por token | 20 por minuto | Consultar un RUC |
| Público por dirección IP | 60 por minuto | Catálogos y especificación OpenAPI |
| Sin token por dirección IP | 60 por minuto | Solicitudes sin cabecera Authorization o con el token en la URL. Nunca bloquea a un token válido |
| Token inválido o revocado por dirección IP | 20 en 5 minutos | Solicitudes con un token inválido o revocado. Nunca bloquea a un token válido |
Una emisión cuenta a la vez para el límite general, el de emisiones del token y el de emisiones de la empresa. También cuentan las emisiones rechazadas: las que responden 400 o 422 por validación, 415 por el tipo de contenido o 406 por la cabecera Accept. Si pruebas tu integración con muchas solicitudes inválidas seguidas, puedes llegar al límite de emisiones antes de emitir un comprobante. Las ventanas son de un minuto (cinco en el límite de token inválido o revocado) y se reinician al terminar.
Los límites se cuentan en cada servidor del API, así que en algunos momentos se puede admitir algo más de lo indicado. No dependas de ese margen.
Cabeceras
Las respuestas a solicitudes con un token válido (también las de error, como 404 o 422), las de las rutas públicas y todas las 429 informan el límite que está más cerca de agotarse para esa solicitud. Las respuestas 401 (sin token, token inválido o revocado) y 400 TOKEN_EN_URL no traen estas cabeceras:
| Cabecera | Contenido |
|---|---|
RateLimit-Limit | Solicitudes permitidas en la ventana. |
RateLimit-Remaining | Solicitudes que quedan en la ventana actual. |
RateLimit-Reset | Segundos hasta que la ventana se reinicia. |
Retry-After | Solo en 429 (y en algunos 409 y 503): segundos que conviene esperar antes de reintentar. |
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Limit: 20
RateLimit-Remaining: 0
RateLimit-Reset: 18
Retry-After: 18
{"error":{"codigo":"LIMITE_EXCEDIDO","mensaje":"Superaste el límite de 20 emisiones por minuto de este token. Reintenta en 18 segundos.","campo":null,"detalles":[],"requestId":"5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10"}}Cómo reintentar después de un 429
- Espera los segundos de
Retry-Afterantes de repetir la solicitud. - Si repites una emisión, usa la misma
Idempotency-Key: la solicitud rechazada con429no creó el comprobante. - Si procesas lotes, reparte las emisiones en el tiempo: con
RateLimit-RemainingyRateLimit-Resetpuedes calcular el ritmo sin llegar al límite.
Tamaño de las solicitudes
| Elemento | Máximo |
|---|---|
| Cuerpo de la solicitud | 256 KB (413 CUERPO_DEMASIADO_GRANDE) |
| Ítems por factura o nota de crédito | 200 |
| Detalles adicionales por ítem | 3 |
| Campos de información adicional | 14 |
| Pagos por factura | 10 |
| Líneas por retención | 20 |
| Comprobantes por página del listado | 100 |
Si necesitas más
Si tu operación necesita límites mayores, por ejemplo por temporadas con muchas ventas, escribe a [email protected] con el RUC de la empresa y el volumen que esperas. Los límites se amplían por empresa.