QAPI está en beta — la API puede cambiar sin previo aviso. Usá sandbox para pruebas.
QAPIQAPIDocs · by DTEVIA
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

PlanDTEs/mesRate limit
Basic10030 req/min
Starter50060 req/min
Business2,000200 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:

ErrorCausa
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

  1. Leé X-RateLimit-Remaining y ralentizá proactivamente cuando se acerque a 0
  2. Usá colas para emisión masiva en lugar de enviar en ráfaga
  3. Reintentá solo RATE_LIMITED, respetando el Retry-After exacto (no adivines el tiempo)
  4. Guardá X-Request-ID en tu log para cada factura — facilita el soporte
  5. Distribuí la carga a lo largo del minuto si tenés muchas facturas simultáneas

En esta página