Ошибки и лимиты

Все ошибки возвращаются в формате JSON с полем error и опционально дополнительными полями. HTTP-статус соответствует семантике ошибки.

Rate limit

Текущие лимиты на endpoint /api/public/matrix:

• 60 запросов в минуту с одного IP-адреса
• Лимит per-IP — не per-токен (токенов нет)
• При превышении — 429 Too Many Requests с заголовком Retry-After (секунды до сброса окна)

Для /api/public/life-path отдельный rate-limit не настроен — контент статичный, кэшируется заголовком Cache-Control: public, max-age=86400 на стороне клиента и промежуточных прокси.

Пример ответа 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
}

Retry-стратегия (рекомендация)

Не делайте бесконечный retry. Best practice — экспоненциальный backoff с 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("Превышено количество попыток");
}

Сводная таблица