Límites y buenas prácticas

Límite de peticiones

200 peticiones por minuto por empresa. Se cuenta por id-empresa, todas las rutas /:id-empresa/… comparten ese cupo sin importar desde cuántos servidores salgan.

El cupo lo comparten tus integraciones y la app web

Los usuarios de tu empresa trabajando en la aplicación consumen del mismo cupo. En la práctica no molesta —200 por minuto es mucho— pero tenelo en cuenta si vas a hacer una carga grande en horario de trabajo.

Al superarlo:

{ "error": "Too many requests. Please try again later." }

Es transitorio: esperá unos segundos y reintentá.

Cuota mensual de comprobantes

Tu plan incluye una cantidad mensual de comprobantes —250 en Premium— que podés aumentar según tu necesidad; ver precios. Cada emisión te devuelve el estado del cupo:

{
  "quota": { "granted": 500, "used": 138, "remaining": 362, "periodEnd": "2026-09-16" }
}

Tres reglas:

• Es mensual y no se acumula. Lo que no emitiste este mes no engorda el siguiente.
• Homologación consume el mismo cupo.
• quota puede venir en null — en reintentos idempotentes, que no consumen. Tu cliente tiene que tolerarlo: null no es "cero disponible", es "no hay nada que informar".

Al agotarse, la emisión responde 429 SUBSCRIPTION_QUOTA_EXCEEDED. Al 90% del cupo la cuenta recibe un aviso por email.

Monitoreá quota.remaining

Está en cada respuesta de emisión, gratis. Guardalo y alertá cuando baje de un umbral tuyo: es la forma de enterarte antes de que un lote de facturación se frene a la mitad.

Al superarlas se responde 429 QUOTA_EXCEEDED. La ventana es móvil y el intento rechazado no cuenta, así que se liberan solas.

Los números son holgados para el uso normal. Si tu integración los toca, casi seguro está haciendo en bucle algo que debería hacer una vez.

Tiempos máximos

Ruta	Techo
General	15 s
/arca/*	25 s
Descarga de PDF	25 s

Al agotarse se responde 504. Un 504 en una emisión no significa que el comprobante no se haya emitido: reintentá con la misma idempotency. Ver errores.

Configurá el timeout de tu cliente HTTP por encima de estos valores (30 segundos es un buen número). Un timeout de 10 segundos del lado tuyo corta emisiones que iban a responder bien, y te deja sin saber si el comprobante existe.

Emitir en volumen

ARCA exige numeración consecutiva por punto de venta y tipo, así que la API emite de a un comprobante por vez para cada combinación posNumber + voucherType.

Secuenciá, no paralelices

Lanzar en paralelo comprobantes del mismo punto de venta y tipo no acelera nada —igual se serializan— y sólo produce errores 429 VOUCHER_LOCK_TIMEOUT.

Distintos puntos de venta sí pueden emitir en paralelo, porque cada uno lleva su propia numeración.

Correcto: secuencial por punto de venta

for (const venta of ventas) {
  const comprobante = await emitir(venta)   // uno tras otro
  await guardar(venta.id, comprobante)
}

Incorrecto: paralelo sobre el mismo punto de venta

await Promise.all(ventas.map(emitir))       // → 429 en cascada

Si tenés que emitir mucho y rápido, la forma de paralelizar es por punto de venta: agrupá las ventas por posNumber y corré un flujo secuencial por grupo.

Lista de control para un lote

1. Generá y guardá la idempotency antes de emitir, junto a la venta. Si el proceso se cae a la mitad, al reanudarlo reusás la misma clave y no duplicás nada.
2. Guardá el resultado inmediatamente después de cada comprobante, no al final del lote.
3. No pidas el PDF durante el lote. Se genera en segundo plano; pedilo cuando alguien lo necesite.
4. Cortá al primer error permanente (400, 422): si el primero está mal armado, probablemente lo estén todos.
5. Registrá arcaObservations cuando no venga null: son comprobantes aprobados, pero con algo que ARCA quiso señalar.

Recomendaciones generales

Guardá los identificadores, no los documentos	id, cae, voucherNumber, posNumber, voucherType. El PDF lo pedís cuando haga falta.
Usá externalReference	Es lo que ata el comprobante a tu operación y lo hace buscable después.
Mandá customer.stateId	El único dato estructurado de ubicación. Sin él no hay reportes por jurisdicción, y no se puede reconstruir.
Consultá el padrón	Te asegura la condición fiscal correcta y evita rechazos de ARCA.
Una API Key por sistema	Cada comprobante guarda cuál lo emitió.
Chequeá ok, no el status	Todas las respuestas traen ok; los errores de negocio traen además code.
Probá en homologación	Cambiar a producción es cambiar una variable de entorno.