<!-- source_url: https://docs.mynexusapi.com/v1/guias/limite-de-request | last_updated: 2026-11-19 -->

# Límite de request

La API limita cuántas solicitudes por minuto hace cada integración (200 por defecto, 60 en un sandbox) y los intentos fallidos por IP.

Para que nuestros servicios respondan rápido a todos nuestros clientes,
limitamos cuántas solicitudes puede hacer cada integración por minuto y cuántos
intentos de autenticación fallidos aceptamos desde una misma IP. Si superas un
límite, la API rechaza la petición con un 429 y te dice cuántos segundos esperar
antes de reintentar.

En esta página verás qué se limita y con qué valores, qué cabeceras te informan
cuánto te queda, cómo leerlas en tu código y cómo organizar tus llamadas para no
llegar nunca al límite.

## Conceptos

Un **límite de solicitudes** (en inglés, *rate limit*) fija cuántas peticiones
puedes hacer en una ventana de tiempo; las que pasan del máximo se rechazan y
puedes repetirlas después de esperar. No tiene relación con cuántos comprobantes
puedes emitir, que es lo que mide el [cupo](/v1/guias/glosario#cupo) y se
explica en [Consumo y cuotas](/v1/guias/consumo).

| Concepto | Qué limita | Respuesta al superarlo |
|---|---|---|
| Límite de solicitudes | Las peticiones por minuto, a cualquier endpoint. | 429 con el `codEstado` 5005 (`limite_solicitudes`). |
| Cupo de documentos | Los comprobantes que puedes emitir con tus paquetes vigentes. | 429 con el `codEstado` 4004 (`cupo_agotado`). |

Como los dos responden con el mismo estado HTTP, distínguelos siempre por el
`codEstado` del cuerpo: el primero se resuelve esperando y el segundo no.

## Qué se limita

| Límite | Valor | Se cuenta por | Qué peticiones cuentan |
|---|---|---|---|
| Solicitudes | 200 por minuto por defecto y 60 por minuto en un sandbox. | Por integración: todas tus API Key comparten el mismo contador. | Toda petición a `/v1` que pasa la autenticación, cualquiera sea su resultado (éxito o error). |
| Intentos de autenticación fallidos | 20 por minuto. | Por IP de origen (en IPv6, por prefijo /64). | Solo las peticiones rechazadas con un 401 y el `codEstado` 3009 (`credenciales_invalidas`), o con un 403 y el `codEstado` 3010 (`ip_no_autorizada`). |

Los dos contadores funcionan con una **ventana fija de un minuto de reloj**:
cada uno vale para el minuto en curso, de hh:mm:00 a hh:mm:59, y vuelve a cero
al empezar el siguiente. No es una ventana móvil, así que si gastas las 200
solicitudes en los primeros 10 segundos, tienes que esperar los 50 restantes.

El límite de **solicitudes por integración** vale 200 por minuto salvo que tu
integración tenga otro valor configurado; un [sandbox](/v1/guias/sandbox) se
crea con 60. El valor que se aplica a ti es siempre el que devuelve la cabecera
`X-RateLimit-Limit`.

El límite de **intentos fallidos por IP** protege tu cuenta de quien intenta
adivinar una API Key. Cuando una IP acumula 20 fallos en el minuto, las
peticiones desde esa IP reciben un 429 hasta que termine el minuto, aunque
traigan una API Key correcta y cambies de clave. Una autenticación correcta no
reinicia el contador: expira al terminar el minuto. El detalle está en
[Autenticación](/v1/guias/autenticacion#limite-de-intentos-fallidos).

## Qué pasa al superar el límite

La API rechaza la petición que excede el límite y no la procesa: no se emite
nada, así que puedes repetirla tal cual cuando termine la espera.

| `codEstado` | HTTP | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 5005 (`limite_solicitudes`) | 429 | Superaste el límite de solicitudes por minuto de tu integración. | Espera los segundos que indica `Retry-After` y reintenta. Si es una emisión, usa la misma `Idempotency-Key`. |
| 5005 (`limite_solicitudes`) | 429 | Tu IP acumuló 20 intentos de autenticación fallidos en el minuto. | Corrige la API Key o registra la IP, y espera lo que indica `Retry-After` antes de reintentar. |

El cuerpo de la respuesta es el de cualquier error de la API:

```json
{
  "estado": "error",
  "codEstado": 5005,
  "msgError": "Límite de solicitudes excedido.",
  "errores": []
}
```

| Campo | Tipo | Descripción |
|---|---|---|
| `estado` | string | Siempre `error` para este límite. |
| `codEstado` | integer | Siempre 5005 para este límite. |
| `msgError` | string | Texto fijo del código. |
| `errores` | array de string | En este código siempre viene vacío. |

## Cabeceras de la respuesta

| Cabecera | Cuándo aparece | Significado |
|---|---|---|
| `X-RateLimit-Limit` | En las respuestas a peticiones autenticadas, cuando tu integración tiene un límite configurado. También en el 429 por intentos fallidos, donde vale 20. | El máximo de solicitudes en la ventana de un minuto. |
| `X-RateLimit-Remaining` | Junto con `X-RateLimit-Limit`. | Las solicitudes que te quedan en el minuto en curso, sin contar esta. |
| `X-RateLimit-Reset` | Solo en el 429 con el `codEstado` 5005 (`limite_solicitudes`). | El momento en que se reinicia la ventana, en segundos Unix (epoch). |
| `Retry-After` | En todas las respuestas 429 y 503. | Los segundos que debes esperar antes de reintentar. |

Una respuesta 401 no trae las cabeceras del límite: la petición no llegó a
identificar tu integración, así que no hay un contador que informar.

Así se ve una respuesta normal:

```
HTTP/1.1 200 OK
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 42
```

Y así, una respuesta al superar el límite:

```
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1757341500
Retry-After: 43
Content-Type: application/json

{
  "estado": "error",
  "codEstado": 5005,
  "msgError": "Límite de solicitudes excedido.",
  "errores": []
}
```

### Lee las cabeceras en tu código

Los ejemplos llaman a `GET /v1/contexto` e imprimen el estado HTTP y las
cabeceras del límite. Las cabeceras vienen en todas las respuestas
autenticadas, así que puedes leerlas de la misma forma en cualquier otra
petición.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal.

```bash
curl -s -o /dev/null -D - "https://api-sandbox.mynexusapi.com/v1/contexto" \
  -H "X-Api-Key: $ECUAFACT_API_KEY" | grep -i -E "^HTTP|x-ratelimit|retry-after"
```

```csharp
using System.Net.Http;

string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

using HttpResponseMessage respuesta = await http.GetAsync("/v1/contexto");
string Cabecera(string nombre) =>
    respuesta.Headers.TryGetValues(nombre, out var valores) ? string.Join(",", valores) : "(no viene)";
Console.WriteLine($"HTTP {(int)respuesta.StatusCode}");
Console.WriteLine($"X-RateLimit-Limit: {Cabecera("X-RateLimit-Limit")}");
Console.WriteLine($"X-RateLimit-Remaining: {Cabecera("X-RateLimit-Remaining")}");
Console.WriteLine($"Retry-After: {Cabecera("Retry-After")}");
```

```python
import os
import requests

r = requests.get(
    "https://api-sandbox.mynexusapi.com/v1/contexto",
    headers={"X-Api-Key": os.environ["ECUAFACT_API_KEY"]},
    timeout=30,
)
print("HTTP", r.status_code)
for nombre in ("X-RateLimit-Limit", "X-RateLimit-Remaining", "Retry-After"):
    print(f"{nombre}: {r.headers.get(nombre, '(no viene)')}")
```

```javascript
// Node.js 18 o superior. Guarda como limite.mjs y ejecuta: node limite.mjs
const res = await fetch('https://api-sandbox.mynexusapi.com/v1/contexto', {
  headers: { 'X-Api-Key': process.env.ECUAFACT_API_KEY }
});
console.log('HTTP', res.status);
for (const nombre of ['X-RateLimit-Limit', 'X-RateLimit-Remaining', 'Retry-After']) {
  console.log(`${nombre}: ${res.headers.get(nombre) ?? '(no viene)'}`);
}
```

```php
<?php
$cabeceras = [];
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contexto');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('ECUAFACT_API_KEY')],
    CURLOPT_HEADERFUNCTION => function ($ch, $linea) use (&$cabeceras) {
        $partes = explode(':', $linea, 2);
        if (count($partes) === 2) {
            $cabeceras[strtolower(trim($partes[0]))] = trim($partes[1]);
        }
        return strlen($linea);
    },
]);
curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo 'HTTP ' . $estado . PHP_EOL;
foreach (['x-ratelimit-limit', 'x-ratelimit-remaining', 'retry-after'] as $nombre) {
    echo $nombre . ': ' . ($cabeceras[$nombre] ?? '(no viene)') . PHP_EOL;
}
```

**Resultado esperado.** Con una API Key de sandbox, el estado es 200,
`X-RateLimit-Limit` vale 60, `X-RateLimit-Remaining` muestra las solicitudes que
te quedan en el minuto (por ejemplo 59) y `Retry-After` no aparece. Si ejecutas
el ejemplo más de 60 veces en el mismo minuto, verás un 429, con
`X-RateLimit-Remaining` en 0 y `Retry-After` con los segundos que faltan.

El valor de `Retry-After` depende de la respuesta:

| Respuesta | Valor de `Retry-After` |
|---|---|
| 429 con el `codEstado` 5005 (`limite_solicitudes`) | Los segundos que faltan para que termine el minuto en curso, de 1 a 60. |
| 429 con el `codEstado` 4004 (`cupo_agotado`) | 60. Esperar no repone el cupo; revisa [Consumo y cuotas](/v1/guias/consumo). |
| 503 con el `codEstado` 5002 (`servicio_no_disponible`) | 5. |

## Cómo respetar el límite en tu código

Cuando una respuesta te avisa que llegaste al límite, sigue estos pasos:

1. Lee `X-RateLimit-Remaining` en cada respuesta. Si llega a 0, no hagas la
   siguiente petición hasta el momento que indica `X-RateLimit-Reset`.
2. Si recibes un 429 con el `codEstado` 5005 (`limite_solicitudes`), espera **al menos** los segundos que
   indica `Retry-After` y reintenta la misma petición. Si es una emisión,
   reenvía la misma `Idempotency-Key` con el mismo cuerpo, para que no se emita
   dos veces.
3. Si recibes un 429 con el `codEstado` 4004 (`cupo_agotado`), no reintentes en bucle: el cupo no se
   repone solo y hay que ampliarlo.

Además, organiza tus llamadas para no llegar al límite:

- Usa los [webhooks](/v1/guias/webhooks) para enterarte del resultado de tus
  emisiones. Consultar `GET /v1/operaciones/{idOperacion}` cada segundo gasta tu
  límite sin necesidad.
- En procesos masivos, reparte las emisiones a lo largo del minuto (por ejemplo,
  3 por segundo en lugar de 200 de golpe) y limita cuántas peticiones haces al
  mismo tiempo.

En [Buenas prácticas](/v1/guias/buenas-practicas#reintentos-con-espera-exponencial)
tienes un ejemplo de reintentos con espera exponencial y variación aleatoria
(*jitter*) en varios lenguajes. Si tu volumen necesita más de 200 solicitudes
por minuto de forma sostenida, puedes solicitar un límite mayor para tu
integración por el canal comercial.

## Si usas un SDK o el CLI

Si te integras con nuestros [SDK oficiales](/v1/guias/sdk) o con nuestro
[CLI de Ecuafact](/v1/guias/cli), puedes dejarles buena parte de este trabajo.
La tabla muestra qué hacen ante cada caso y qué te queda por hacer a ti.

| Herramienta | Ante un 429 con el `codEstado` 5005 (`limite_solicitudes`) | Ante un 429 con el `codEstado` 4004 (`cupo_agotado`) |
|---|---|---|
| SDK | Por defecto espera lo que indica `Retry-After` y reintenta solo. Si desactivas la opción `RetryRateLimited`, lanza una excepción de límite que trae los segundos de espera sugeridos. | Nunca reintenta: lanza una excepción de cupo. |
| CLI | Espera lo que indica `Retry-After` y reintenta solo. Además, cuando una respuesta le indica que ya no te quedan solicitudes en el minuto, espera al minuto siguiente antes de enviar la próxima y te avisa en la terminal cuántos segundos faltan. Así, en un lote grande casi nunca llega a recibir un 429. | No reintenta. El comando termina con el código de salida 6, que en un script te permite distinguir este caso. |

Si usas el CLI, no necesitas leer las cabeceras del límite, porque el comando lo
respeta por ti. Si lo usas desde un script, revisa el código de salida, que se
explica en la [referencia del CLI](/v1/guias/cli-referencia#codigos-de-salida).

## Siguientes pasos

- [Buenas prácticas](/v1/guias/buenas-practicas): estrategia de reintentos con código listo para copiar.
- [Límites](/v1/guias/limites): tamaño del cuerpo, paginación y otros topes por petición.
- [Consumo y cuotas](/v1/guias/consumo): consulta tu cupo de documentos antes de un lote grande.
- [Errores](/v1/guias/errores): todos los códigos y si se reintentan.
