Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

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 y se explica en Consumo y cuotas.

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 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.

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:

{
  "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.

Importante

Ambiente de pruebas: sin validez fiscal.

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"
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")}");
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)')}")
// 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
$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.
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 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 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 o con nuestro CLI de Ecuafact, 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.

Siguientes pasos#

  • Buenas prácticas: estrategia de reintentos con código listo para copiar.
  • Límites: tamaño del cuerpo, paginación y otros topes por petición.
  • Consumo y cuotas: consulta tu cupo de documentos antes de un lote grande.
  • Errores: todos los códigos y si se reintentan.
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.