Error: rate_limit_exceeded

Qué significa

Tu aplicación envió demasiados requests en un corto periodo de tiempo y superó el límite asignado a tu API key o tenant.

Envelope de ejemplo

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limit_exceeded",
    "message": "Límite de requests excedido. Reintenta en 1 segundo.",
    "doc_url": "https://docs.emitia.co/errors/rate_limit_exceeded",
    "request_id": "req_01HX…"
  }
}

HTTP status: 429 Too Many Requests

Límites por defecto

Nivel	Límite
Por API key	100 req/s, burst 200
Por tenant (todas las keys)	500 req/s

Los límites son configurables por plan. Contacta soporte si necesitas límites más altos.

Headers de respuesta

La respuesta 429 incluye:

RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1716480601
Retry-After: 1

• Retry-After indica los segundos a esperar antes del siguiente intento.

Cómo resolverlo

1. Lee el header Retry-After y espera ese número de segundos.
2. Implementa backoff exponencial con jitter en tu cliente.
3. Distribuye los requests en el tiempo si estás enviando lotes grandes.

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 5,
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err: unknown) {
      const e = err as { status?: number; headers?: { get: (k: string) => string | null } };
      if (e?.status === 429) {
        const retryAfter = parseInt(e.headers?.get('Retry-After') ?? '1', 10);
        const jitter = Math.random() * 500; // ms
        await new Promise((r) => setTimeout(r, (retryAfter * 1000) + jitter));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Max retries reached');
}

Ver también

• Conceptos: Idempotencia — retry seguro con Idempotency-Key