Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.