Límites
Límite de peticiones
Cada credencial admite 120 peticiones por minuto. Toda respuesta a una petición que cuenta contra el límite lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (marca de tiempo Unix del reinicio): las de una credencial válida a una ruta de la API, también un 404 de un recurso que no existe, un 422 y el propio 429. No cuentan ni llevan esas cabeceras un 401 (sin credencial o con una que no vale, que no tiene límite propio), un 404 de una ruta que no existe y un 405 de un método que la ruta no admite. Al superarlo, la API responde 429 rate_limited con Retry-After en segundos. Los lotes cuentan como una sola petición y los listados con updated_since evitan recorrer todo el catálogo.
Las dos rutas del PDF (GET /sales/{uuid}/document/pdf y GET /sales/{uuid}/adjustment-notes/{note}/document/pdf) tienen además un límite propio de 20 PDF por minuto por credencial, que también cuentan contra los 120. Al superarlo responden 429 rate_limited, y en esas respuestas X-RateLimit-Limit dice 20. Un PDF caro (más de 50 líneas o más de 20000 caracteres de descripción) se atiende de uno en uno en todo el sistema: si otro se está generando, la ruta responde 429 rate_limited con Retry-After, aunque la credencial no haya llegado a su límite. En cualquier 429 se obedece Retry-After.
Abrir un enlace firmado (ver Compartir el documento) no cuenta contra los 120 ni contra los 20 PDF de la credencial. Los enlaces tienen sus propios límites: 20 aperturas por minuto de un mismo documento, por cualquiera de sus enlaces, y 60 aperturas por minuto desde una misma dirección IP, en las que también cuentan los enlaces vencidos o alterados. Al superar cualquiera de los dos, el enlace responde 429 con Retry-After y una página corta para el cliente. Abrir de nuevo el mismo PDF dentro de los 10 minutos que vive el enlace no lo genera otra vez.
Tamaños
| Límite | Valor |
|---|---|
| Líneas de una venta | 200 |
| Cargos de una nota de débito | 200 |
| Líneas de un documento cuyo PDF se pide por API | 100 |
| Caracteres de descripción de un documento cuyo PDF se pide por API | 100000 |
Elementos de POST /customers/batch y POST /products/batch |
100 |
Ventas de un lote (POST /sales/batches) |
1000 |
Filas por página (per_page) |
100 |
Caracteres de Idempotency-Key |
128 |
Una petición que supera un tamaño responde 422 validation_failed, salvo el PDF: una venta admite 200 líneas, pero el PDF de un documento que pasa de 100 líneas o de 100000 caracteres de descripción responde 422 document_too_long. Ese documento, sellado o firmado en contingencia, se entrega con POST /sales/{uuid}/document/send, que adjunta el JSON y, hasta 200000 caracteres de descripción, el PDF. Una nota o cualquier otro documento se piden desde el panel.