Лимиты и квоты

Два разных условия возвращают одинаковый HTTP 429:

Решения у них разные. Первое — "подождать и повторить"; второе — "потратить больше или ждать сброса".

Rate limit (на ключ)

У каждого API-ключа есть rateLimitPerMinute (по умолчанию 60). Запросы выше этого порога возвращают:

HTTP/1.1 429 Too Many Requests
Retry-After: 15
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1717201234

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit of 60 req/min exceeded. Retry after 15 seconds."
}

Проверки

1. Проверьте заголовки. X-RateLimit-Limit — потолок per-key, X-RateLimit-Remaining — сколько осталось в текущем окне, Retry-After — сколько секунд ждать.

2. Найдите ключ, упирающийся в лимит. Часто несколько фронтов делят один widget-ключ. Откройте Search → API Keys → ключ → "Last 24 hours" и поищите всплески.

3. Делаете один-поиск-на-нажатие? Наивный автокомплит может выпускать 5–10 запросов в секунду на пользователя. С 12 активными пользователями это 3 600 req/min с одного ключа.

Исправление

Паттерн повтора

Уважайте Retry-After. Не повторяйте до его истечения, иначе bucket остаётся переполненным:

async function searchWithRateLimitRetry(query: string) {
	for (let attempt = 0; attempt < 3; attempt++) {
		try {
			return await client.search({ q: query });
		} catch (err) {
			if (err instanceof AacSearchError && err.code === "rate_limit") {
				const retryAfterSec = Number(err.response?.headers.get("Retry-After") ?? 5);
				await new Promise((r) => setTimeout(r, retryAfterSec * 1000));
				continue;
			}
			throw err;
		}
	}
	throw new Error("rate-limited after 3 attempts");
}

Quota exceeded (месячная)

Когда организация исчерпала месячную норму search-юнитов тарифа:

HTTP/1.1 429 Too Many Requests

{
  "error": "quota_exceeded",
  "message": "Monthly search-unit quota exhausted. Upgrade your plan or wait for reset."
}

Один search-юнит = 1 поисковый запрос ИЛИ 1 проиндексированный документ. См. Тарифы и лимиты для цифр по тарифам.

Проверки

1. Где вы по тарифу? Settings → Billing → Usage. Прогресс-бар показывает текущий расход против потолка.
2. Причина ожидаемая? Если вчера запустили новый сторфронт — всплеск ожидаем. Если нет — ищите в логах беглые скрипты.
3. Включён ли wallet overage? Платные тарифы могут включить overage — после этого запросы выше soft cap списываются с кошелька, а не возвращают 429.

Исправление

После включения overage следующий запрос выше soft cap списывает с кошелька (по цене за 1k search-юнитов). Hard cap блокирует только когда сам кошелёк пуст.

Разница между soft и hard cap

Без overage soft и hard cap совпадают.

Пакет диагностики

Связанные

• Ошибки и rate limits — матрица кодов ошибок
• Тарифы и лимиты — уровни квот
• Биллинговые лимиты — биллинг-специфичные проблемы
• Browser SDK — паттерн дебаунса / useDeferredValue