Límites por empresa

Cada empresa tiene un presupuesto propio en producción (sk_test_ y sk_live_): lo que una empresa gasta no afecta a otra, y test y live de la misma empresa no comparten cupo. El sandbox (sk_sandbox_) tiene límites propios.

Valores por defecto

Límite	Valor	Respuesta al superarlo
Escrituras (todo método distinto de GET)	100 por minuto	429 rate_limited, limit: writes
Lecturas (GET)	300 por minuto	429 rate_limited, limit: reads
Documentos en proceso (pending, sending, dian_unavailable)	1.000	429 in_flight_limited, Retry-After: 30
Emisiones síncronas abiertas (solicitudes que esperan el resultado)	5 a la vez	429 concurrency_limited, limit: sync_open
Lotes en admisión (portal)	1 a la vez	429 concurrency_limited, limit: batch_admission
Lotes creados (portal)	5 por minuto	429 rate_limited, limit: batches
Reenvíos del correo al comprador, por empresa	10 por minuto	429 rate_limited, limit: resends
Reenvíos del correo al comprador, por documento	5 en 24 horas	429 rate_limited, limit: document_resends
Documentos nuevos en test (habilitación)	1.000 por mes	429 test_quota_exceeded, sin Retry-After

El minuto es el minuto UTC del reloj, no una ventana móvil. REST y MCP cuentan juntos. La consulta del adquirente (GET .../acquirers/...) es una lectura y además conserva su propio cupo. Una herramienta del MCP sin company_id no consume tasa. Los valores se configuran por despliegue y solo un administrador de foliios puede sobrescribirlos para una empresa; tú no puedes cambiarlos desde la API, el MCP ni el portal. Consulta siempre los vigentes en la referencia y no los copies a tu código.

Cabeceras

Las respuestas REST contadas llevan:

• X-RateLimit-Limit: el límite de la clase (escrituras o lecturas).
• X-RateLimit-Remaining: lo que queda en el minuto.
• X-RateLimit-Reset: segundos hasta que el contador vuelve a cero.

Un 429 además trae Retry-After (al menos 1 segundo; en los límites por empresa coincide con X-RateLimit-Reset) y el miembro limit en el cuerpo problem+json. En el MCP la respuesta HTTP es 200 y el error va en la herramienta, con code, limit y retry_after_secs; las X-RateLimit-* van en las cabeceras HTTP.

Qué se cuenta primero

El orden de los controles al emitir es: tasa, idempotencia, saldo (402, solo live), documentos en proceso y cola. Por eso:

• Cada intento gasta una unidad de tasa, también la repetición de una emisión con la misma Idempotency-Key y la que falla después.
• Con la tasa agotada, una repetición recibe 429 y no el documento original; espera Retry-After y repite con la misma clave.
• Con el tope en proceso lleno, una repetición idempotente sí devuelve el documento original.
• Un 429 in_flight_limited no consume número ni crea documento.

Documentos en proceso

El tope de 1.000 es aproximado: se cuenta con consistencia eventual, así que emisiones concurrentes pueden pasarlo por poco y un lote admitido puede dejarlo por encima. El cupo se libera cuando un documento sale de pending, sending o dian_unavailable (aceptado, rechazado, failed, contingencia).

Emisiones síncronas abiertas

Una emisión, un reenvío (resubmit) o un reintento (retry) que espera el resultado de la DIAN ocupa un cupo sync_open de la empresa mientras espera, y lo devuelve al responder. Con todos ocupados, la siguiente solicitud que quiera esperar responde 429 concurrency_limited con limit: sync_open y Retry-After, antes de emitir nada: no consume número ni crea documento. Una solicitud con ?wait=0 no espera y no ocupa cupo. Ver cuánto espera la emisión.

Ese 429 trae X-RateLimit-Limit (los cupos de la empresa: 5, o 2 en el sandbox), X-RateLimit-Remaining: 0, y Retry-After y X-RateLimit-Reset con los mismos segundos, entre 1 y 25 (lo habitual es 25). Es el tiempo máximo que puede tardar en liberarse un cupo: la solicitud que lo ocupa lo devuelve al responder, a lo sumo tras los 23 segundos de la espera más larga, con 2 de margen. Suele liberarse antes, así que puedes reintentar antes con la misma Idempotency-Key o emitir con ?wait=0.

Reenvíos al comprador

Reenviar el correo de un documento (POST .../documents/{document_id}/deliver, la herramienta resend_document del MCP o el botón del portal) tiene dos topes propios en test y en live. En live cada reenvío es un correo real; en test el correo se guarda en el buzón de habilitación (o se envía, si tu empresa tiene un tope de correos reales y aún queda del día) y el reenvío cuenta igual. Los tres canales cuentan juntos:

• Por empresa: 10 reenvíos por minuto UTC. Al superarlo, 429 rate_limited con limit: resends; Retry-After es lo que queda del minuto (entre 1 y 60 segundos).
• Por documento: 5 reenvíos en 24 horas móviles. Al superarlo, 429 rate_limited con limit: document_resends; Retry-After son los segundos hasta que el reenvío más antiguo sale de la ventana, y puede ser de horas (hasta 86.400). No reintentes en bucle: espera ese tiempo o avísale a la persona.

En los dos casos no se envía ni se encola nada. En el MCP el error llega en la herramienta, con code: rate_limited, limit y retry_after_secs.

Qué no cuenta: el primer envío automático al aceptarse el documento, los reintentos automáticos de un mismo reenvío, y las solicitudes que se rechazan por otra razón (404, 409, 422), incluida la pregunta 409 confirmation_required del portal cuando la dirección no es del comprador.

El tope por empresa es uno de los valores que foliios puede ajustar para tu empresa; el tope por documento es igual para todas. Si el contador por minuto falla de nuestro lado, el reenvío pasa (si el contador falla); el tope por documento no depende de ese contador. El sandbox no tiene estos topes: sus correos se quedan en el buzón de pruebas y los reenvíos cuentan como escrituras del sandbox.

Lotes

Un lote entra completo o no entra. En live se admite solo si el saldo más el sobregiro cubre todos sus documentos (si no, 402 overdraft_limit_reached) y si los documentos en proceso más su tamaño no pasan el tope (si no, 429 in_flight_limited); en ambos casos no se encola ninguno. Una vez admitido, ningún documento queda failed por un límite temporal. No se reserva saldo: si el sobregiro se alcanza a mitad del lote, algún documento puede quedar failed por saldo.

Cuota mensual en test

En habilitación (sk_test_) cada empresa emite hasta 1.000 documentos nuevos por mes calendario, en hora de Colombia. El documento 1.001 responde 429 test_quota_exceeded con el miembro limit y sin Retry-After: reintentar no sirve, el cupo vuelve el día 1. No cuentan el set de habilitación, las repeticiones con la misma Idempotency-Key (devuelven el original) ni los ambientes live y sandbox. No se consume número cuando se rechaza. Si necesitas más cupo, pídele a foliios que lo ajuste para tu empresa.

Si el contador falla

El límite no frena las emisiones por su propia caída: si el contador no responde, la solicitud pasa y foliios lo registra y lo alerta. La excepción es la cuota mensual de test: si su contador falla, la emisión en test se rechaza con un error de servicio (no se consume número) y puedes repetirla con la misma Idempotency-Key.

En el sandbox hay otra excepción: si falla el contador de las emisiones síncronas abiertas, tu solicitud no espera el resultado. El documento se emite igual y la respuesta llega de inmediato, como con ?wait=0: 202 con Location, sin Retry-After. Consulta el documento con GET o espera el webhook. En test y live la solicitud pasa y espera como siempre.

Cómo reaccionar

1. Lee Retry-After y espera ese tiempo; ante 429 repetidos, aumenta la pausa.
2. Reintenta con la misma Idempotency-Key y el mismo cuerpo (reintentos).
3. Reparte las escrituras a lo largo del minuto en vez de lanzarlas todas juntas; para volúmenes grandes usa lotes desde el portal.
4. Si tu volumen legítimo necesita más cupo, pídele a foliios que lo ajuste para tu empresa.