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:
- Lee
X-RateLimit-Remainingen cada respuesta. Si llega a 0, no hagas la siguiente petición hasta el momento que indicaX-RateLimit-Reset. - Si recibes un 429 con el
codEstado5005 (limite_solicitudes), espera al menos los segundos que indicaRetry-Aftery reintenta la misma petición. Si es una emisión, reenvía la mismaIdempotency-Keycon el mismo cuerpo, para que no se emita dos veces. - Si recibes un 429 con el
codEstado4004 (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.