Errores y límites

Todos los errores se devuelven en formato JSON con el campo error y, opcionalmente, campos adicionales. El estado HTTP corresponde a la semántica del error.

Rate limit

Límites actuales del endpoint /api/public/matrix:

• 60 solicitudes por minuto desde una misma dirección IP
• Límite por IP, no por token (no hay tokens)
• Al superarlo — 429 Too Many Requests con el encabezado Retry-After (segundos hasta el reinicio de la ventana)

Para /api/public/life-path no hay un rate-limit propio — el contenido es estático y se cachea con el encabezado Cache-Control: public, max-age=86400 en el cliente y los proxies intermedios.

Ejemplo de respuesta 429

HTTP/1.1 429 Too Many Requests
Retry-After: 27
Cache-Control: no-store
Content-Type: application/json

{
  "error": "Too many requests",
  "retry_after_seconds": 27
}

Estrategia de reintento (recomendación)

No hagas reintentos infinitos. La mejor práctica es un backoff exponencial con jitter:

async function fetchWithRetry(url, opts = {}, maxAttempts = 4) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch(url, opts);
    if (res.status === 429) {
      const wait = Number(res.headers.get("retry-after") ?? 5);
      const jitter = Math.random() * 0.4 + 0.8; // ±20%
      await new Promise(r => setTimeout(r, wait * 1000 * jitter));
      continue;
    }
    return res;
  }
  throw new Error("Se superó el número de intentos");
}

Tabla resumen