Guías
Rate Limiting
Límites de velocidad por plan, headers de respuesta y estrategias de retry en QAPI.
QAPI aplica un límite de requests por minuto a cada API key, según el plan de tu cuenta.
Límites por plan
| Plan | DTEs/mes | Rate limit |
|---|---|---|
| Basic | 100 | 30 req/min |
| Starter | 500 | 60 req/min |
| Business | 2,000 | 200 req/min |
Headers de rate limit
Cada respuesta incluye estos headers:
Propiedad
Tipo
Respuesta cuando se supera el límite
Ejemplo HTTP
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 43
Content-Type: application/json
{
"type": "https://docs.dtevia.com.gt/errors/rate-limited",
"title": "RATE_LIMITED",
"status": 429,
"detail": "Límite de requests excedido. Reintentar en 43s",
"instance": "/v1/invoices"
}Estrategia de retry
Solo RATE_LIMITED trae el header Retry-After, y es el único 429 que se resuelve
esperando unos segundos. Los 429 de cuota (SANDBOX_LIMIT_REACHED, MONTHLY_QUOTA_EXCEEDED,
OVERAGE_CAP_REACHED) no lo traen: reintentarlos no sirve, hay que leer el title y resolver
la causa. Los ejemplos reintentan solo cuando viene Retry-After.
Implementación
async function fetchWithRetry(
url: string,
options: RequestInit,
maxRetries = 3
): Promise<Response> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const res = await fetch(url, options);
const retryAfter = res.headers.get('retry-after');
// Solo RATE_LIMITED trae Retry-After: un 429 de cuota no se arregla reintentando.
if (res.status !== 429 || !retryAfter) return res;
if (attempt === maxRetries) throw new Error('Max retries reached');
console.log(`Rate limited. Reintentando en ${retryAfter}s...`);
await new Promise(r => setTimeout(r, Number(retryAfter) * 1000));
}
throw new Error('Unreachable');
}import axiosRetry from 'axios-retry';
axiosRetry(axios, {
retries: 3,
// Solo RATE_LIMITED trae Retry-After: un 429 de cuota no se arregla reintentando.
retryCondition: (error) =>
error.response?.status === 429 && error.response.headers['retry-after'] != null,
retryDelay: (retryCount, error) =>
Number(error.response?.headers['retry-after']) * 1000,
});import time
def fetch_with_retry(url: str, max_retries: int = 3, **kwargs) -> httpx.Response:
for attempt in range(max_retries + 1):
res = httpx.post(url, **kwargs)
retry_after = res.headers.get("retry-after")
# Solo RATE_LIMITED trae Retry-After: un 429 de cuota no se arregla reintentando.
if res.status_code != 429 or retry_after is None:
return res
if attempt == max_retries:
raise Exception("Max retries alcanzados")
retry_after = int(retry_after)
print(f"Rate limited. Reintentando en {retry_after}s...")
time.sleep(retry_after)
raise Exception("Unreachable")Errores de límite de cuota
Rate limit vs otros límites del plan
Distintos de rate limiting (velocidad), existen otros límites por plan:
| Error | Causa |
|---|---|
RATE_LIMITED (429) | Demasiadas requests por minuto |
SANDBOX_LIMIT_REACHED (429) | Superaste el límite diario de facturas de prueba por tipo de DTE |
MONTHLY_QUOTA_EXCEEDED (429) | El proyecto agotó su cuota mensual de DTEs asignada (solo live) |
OVERAGE_CAP_REACHED (429) | La cuenta llegó al máximo de DTEs del mes, contando los excedentes |
Buenas prácticas
- Leé
X-RateLimit-Remainingy ralentizá proactivamente cuando se acerque a 0 - Usá colas para emisión masiva en lugar de enviar en ráfaga
- Reintentá solo
RATE_LIMITED, respetando elRetry-Afterexacto (no adivines el tiempo) - Guardá
X-Request-IDen tu log para cada factura — facilita el soporte - Distribuí la carga a lo largo del minuto si tenés muchas facturas simultáneas