En esta página
Límites
La API pone topes al tamaño del cuerpo, las cabeceras, el comprobante, las consultas, el ritmo de solicitudes y el cupo; aquí está cada valor y su error.
Cada petición a la API tiene topes concretos: cuánto puede pesar el cuerpo, qué caracteres admite una cabecera, cuántas líneas lleva un comprobante o qué rango de fechas acepta una consulta. Aquí tienes todos esos valores en tablas, junto con la respuesta que recibes si superas cada uno.
Los topes de tamaño, cabeceras, comprobante y consultas son los mismos en pruebas y en producción. Lo que cambia entre ambientes es el ritmo de solicitudes por minuto, que en un sandbox es menor, y el cupo, que se lleva por separado en cada ambiente. El límite de solicitudes por minuto tiene su propia página, Límite de request, y aquí solo aparece resumido.
Solicitud#
| Límite | Valor | Si lo superas |
|---|---|---|
Tamaño del cuerpo en cualquier endpoint de emisión por tipo (por ejemplo, POST /v1/contribuyentes/{identificacion}/facturas) y en su validación (POST .../{tipo}/validar) |
2 MiB (2.097.152 bytes) | 413 con el codEstado 3006 (cuerpo_excedido). |
Tamaño del cuerpo en el resto de POST y PUT |
1 MiB (1.048.576 bytes) | 413 con el codEstado 3006 (cuerpo_excedido). |
Tamaño del archivo del logo en POST /v1/contribuyentes/{identificacion}/perfil/logo |
512 KB, en PNG o JPEG | 400 con el codEstado 3003 (solicitud_invalida), como se explica en Perfil del emisor. |
| Profundidad del JSON (objetos y arreglos anidados) | 32 niveles | En la emisión y su validación, 422 con el codEstado 3002 (comprobante_invalido); en el resto, 400 con el codEstado 3003 (solicitud_invalida). |
Content-Type de la emisión |
application/json, application/xml o text/xml |
Un tipo distinto responde 415 con el codEstado 3003 (solicitud_invalida). |
Un comprobante normal pesa unos pocos KB. Si te acercas a 2 MiB, revisa que no
estés enviando datos repetidos o imágenes dentro de infoAdicional.
Cabeceras#
| Cabecera | Regla | Si no la cumples |
|---|---|---|
X-Api-Key |
Es obligatoria en todo /v1. |
401 con el codEstado 3009 (credenciales_invalidas) si falta o es inválida; 403 con el codEstado 3010 (ip_no_autorizada) si la IP no está permitida. |
Idempotency-Key |
Es obligatoria en la emisión. Tiene de 1 a 128 caracteres y solo admite letras ASCII sin tildes (A-Z, a-z), dígitos (0-9) y los símbolos - _ . : /. |
400 con el codEstado 3003 (solicitud_invalida). |
X-Api-Version |
Es opcional. Si la envías, debe ser la versión vigente, 2026-11-16. |
400 con el codEstado 3007 (version_no_soportada). |
X-Correlation-Id |
Es opcional. Si la envías con 1 a 64 caracteres A-Z, a-z, 0-9, ., _, -, la API la usa y te la devuelve; si no cumple, la API genera una nueva. |
No hay error. |
X-Additional-Info |
Es opcional y sirve para identificar la solicitud al pedir soporte, por ejemplo MiERP/4.2 sucursal=norte. Va una sola vez por solicitud, solo con ASCII imprimible (0x20 a 0x7E) y como máximo 256 caracteres. No se guarda con el comprobante. No pongas datos personales ni secretos. |
No hay error; si no cumple, no podremos usarla para ubicar tu solicitud. |
Una Idempotency-Key se recuerda durante 7 días dentro de tu integración y
del ambiente. Cómo generarla y guardarla se explica en
Buenas prácticas.
Consultas#
Las consultas de listado y de búsqueda validan sus filtros antes de ejecutarse.
Un valor fuera de rango responde 400 con el codEstado 3012
(filtros_invalidos), y el campo errores indica qué filtro corregir.
| Consulta | Filtro | Regla |
|---|---|---|
GET /v1/operaciones |
desde y hasta |
Formato yyyy-MM-dd, desde el 2000-01-01. hasta no puede ser anterior a desde y entre ambas fechas puede haber como máximo 366 días. Sin fechas se usan los últimos 30 días. |
GET /v1/operaciones |
pagina |
De 1 a 10000. Por defecto, 1. |
GET /v1/operaciones |
tamanoPagina |
De 1 a 100. Por defecto, 20. |
GET /v1/operaciones |
buscar |
Hasta 100 caracteres, sin caracteres de control. |
GET /v1/operaciones |
tipoDocumento |
01, 03, 04, 05, 06 o 07. |
GET /v1/consultas/contribuyentes |
max |
De 1 a 30. Por defecto, 10. |
GET /v1/consultas/contribuyentes |
apellidos y clase |
apellidos es obligatorio. clase admite PersonaNatural (por defecto), Sociedad o SociedadPublica. |
GET /v1/catalogos/{nombre} |
nombre |
Una clave que devuelva GET /v1/catalogos; otra responde 404 con el codEstado 3013 (no_encontrado). |
Estructura del comprobante#
| Campo o colección | Regla | Si no la cumples |
|---|---|---|
origenReferencia |
Es obligatorio, con 1 a 64 caracteres del mismo juego que Idempotency-Key. |
422 con el codEstado 3002 (comprobante_invalido). |
referenciaExterna |
Es obligatorio, con 1 a 128 caracteres del mismo juego que Idempotency-Key. |
422 con el codEstado 3002 (comprobante_invalido). |
infoTributaria.ruc |
Solo admite dígitos, de 5 a 13. | 422 con el codEstado 3002 (comprobante_invalido). |
infoTributaria.estab y infoTributaria.ptoEmi |
Solo admiten dígitos, como máximo 3, y se completan con ceros a la izquierda. | 422 con el codEstado 3002 (comprobante_invalido). |
infoTributaria.secuencial |
Es opcional y solo admite dígitos, como máximo 9, de 1 a 999999999. Si lo omites o lo envías en ceros, asignamos el siguiente. | 422 con el codEstado 3002 (comprobante_invalido). |
detalles |
Lleva de 1 a 1000 líneas. | 422 con el codEstado 3002 (comprobante_invalido). |
detalles[].detallesAdicionales |
Admite hasta 3 por línea. | 422 con el codEstado 3002 (comprobante_invalido). |
info.pagos |
Lleva de 1 a 20 en la factura y en la liquidación de compra. | 422 con el codEstado 3002 (comprobante_invalido). |
infoAdicional |
Admite hasta 15 objetos { "nombre", "valor" }. |
422 con el codEstado 3002 (comprobante_invalido). |
| Campos desconocidos o repetidos | No se admiten. | 422 con el codEstado 3002 (comprobante_invalido). |
Las reglas completas de cada tipo de comprobante están en Comprobantes electrónicos y en la guía de cada tipo.
Tasa de peticiones#
| Límite | Valor | Si lo superas |
|---|---|---|
| Solicitudes por integración | 200 por minuto por defecto y 60 en un sandbox. | 429 con el codEstado 5005 (limite_solicitudes). |
| Intentos de autenticación fallidos por IP | 20 por minuto. | 429 con el codEstado 5005 (limite_solicitudes). |
Consultas a GET /estado por IP, sin API Key |
60 por minuto. | 429 con el codEstado 5005 (limite_solicitudes). |
El detalle, las cabeceras X-RateLimit-* y cómo esperar con Retry-After están
en Límite de request.
Cupo#
El cupo es la cantidad de comprobantes que puedes emitir en cada ambiente con tus paquetes pagados y vigentes. La emisión responde así según tu saldo:
| Situación | Respuesta de la emisión |
|---|---|
| Te quedan documentos disponibles | 202 Accepted. |
| No te quedan documentos | 429 con el codEstado 4004 (cupo_agotado). |
| La solicitud tiene errores de forma (400, 409 o 413) | No consume cupo. |
| El comprobante no pasa la validación (422) | Consume 1 documento como intento. Repetir la misma Idempotency-Key con el mismo cuerpo no consume otro. |
Cada comprobante que el SRI autoriza o rechaza consume un documento de tu cupo.
Un comprobante cancelado no lo consume. Las consultas, las validaciones con
/validar, las descargas y la gestión del perfil y de los webhooks tampoco
consumen cupo.
Antes de un lote grande, consulta tu saldo con
GET /v1/consumo.
Siguientes pasos#
- Límite de request: cuántas solicitudes por minuto puedes hacer y cómo esperar.
- Errores: qué significa cada código y si se reintenta.
- Comprobantes electrónicos: reglas completas de la Estructura del comprobante.
- Consumo y cuotas: consulta y amplía tu cupo.