Rate limiting

La API de Correo de Yolani aplica límites de tasa para garantizar un uso justo y estable del servicio.

Límite por defecto

  • 100 peticiones por minuto por API key
  • El contador se reinicia cada minuto (ventana deslizante)

Headers de respuesta

En cada respuesta, la API incluye headers que indican el estado del rate limit:

HeaderDescripción
RateLimit-LimitNúmero máximo de peticiones permitidas por minuto
RateLimit-RemainingPeticiones restantes en la ventana actual
RateLimit-ResetMomento en que se reinicia el contador (timestamp o segundos)

Respuesta cuando se excede el límite

Si superas las 100 peticiones por minuto:

HTTP 429 Too Many Requests

{
  "success": false,
  "error": "Rate limit exceeded. Max 100 requests per minute."
}

Cómo manejar el rate limit

  1. Implementar backoff exponencial: Si recibes 429, espera unos segundos y reintenta. Aumenta el tiempo de espera en cada reintento.
  2. Cola de mensajes: En lugar de enviar todos los correos de golpe, encólalos y envía en lotes pequeños.
  3. Monitorear los headers: Usa RateLimit-Remaining para saber cuántas peticiones te quedan y reducir el ritmo antes de llegar al límite.

Ejemplo de reintento con backoff (JavaScript)

async function sendWithRetry(url, options) {
  const maxRetries = 3;
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const wait = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, wait));
      continue;
    }
    return res;
  }
  throw new Error('Rate limit exceeded after retries');
}