<!-- source_url: https://docs.mynexusapi.com/v1/guias/limites | last_updated: 2026-11-16 -->

# 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](/v1/guias/limite-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](/v1/guias/perfil-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](/v1/guias/buenas-practicas#idempotencia).

## 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`](/v1/guias/consulta-operacion#listado-de-operaciones-por-contribuyente) | `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`](/v1/guias/consulta-contribuyente-nombre) | `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](/v1/guias/emision) 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](/v1/guias/limite-de-request).

## Cupo

El [cupo](/v1/guias/glosario#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`](/v1/guias/consumo).

## Siguientes pasos

- [Límite de request](/v1/guias/limite-de-request): cuántas solicitudes por minuto puedes hacer y cómo esperar.
- [Errores](/v1/guias/errores): qué significa cada código y si se reintenta.
- [Comprobantes electrónicos](/v1/guias/emision): reglas completas de la Estructura del comprobante.
- [Consumo y cuotas](/v1/guias/consumo): consulta y amplía tu cupo.
