Лимиты биллинга

Когда запрос возвращает quota_exceeded или функция молча недоступна, причина — одна из трёх: месячная квота поисковых единиц, бюджет перерасхода кошелька или функциональное ограничение уровня тарифа. Для каждой — своё решение.

Симптомы

См. Тарифы и лимиты для цифр по каждому тарифу.

Проверка 1: ваше положение по месячной квоте

Откройте Настройки → Биллинг → Использование. Отображаются три показателя:

Вы также можете получить это программно с помощью административного ключа:

curl -X GET https://app.aacsearch.com/api/v1/projects/<projectId>/usage \
  -H "Authorization: Bearer aa_admin_..."

Ответ включает searchUnitsUsed, searchUnitsCap, walletBalanceMinor (в копейках), periodStartUtc, periodEndUtc.

Проверка 2: бюджет перерасхода

Если вы на платном тарифе, вы можете включить перерасход за счёт кошелька. Когда он включён, запросы сверх мягкого лимита оплачиваются из кошелька (с тарификацией за 1 тыс. поисковых единиц) вместо возврата 429.

Включите перерасход в Настройки → Биллинг → Бюджет перерасхода. Установите максимальный месячный потолок расходов, чтобы не было сюрпризов.

Проверка 3: функциональные ограничения

Некоторые функции недоступны на определённых уровнях тарифа:

Запрос к ограниченной функции возвращает:

{
  "error": "feature_not_available_on_plan",
  "message": "Curations require the Pro plan or higher.",
  "requiredPlan": "pro",
  "upgradeUrl": "https://app.aacsearch.com/settings/billing"
}

Обновите тариф в Настройки → Биллинг → Сменить тариф.

Проверка 4: потолки уровня тарифа

Каждый тариф ограничивает количество индексов:

Попытка создать ещё один возвращает:

{
  "error": "plan_limit_reached",
  "message": "Free plan allows 1 index. Upgrade to Starter for up to 3.",
  "requiredPlan": "starter"
}

Мягкий vs жёсткий лимит (подробно)

Срабатывание мягкого лимита:
  ├─ Email + алерт в дашборде контакту по биллингу
  ├─ Запросы всё ещё обслуживаются, если включён бюджет перерасхода
  └─ Кошелёк начинает списываться, если перерасход включён

Срабатывание жёсткого лимита:
  ├─ Все эндпоинты поиска и индексации возвращают 429 quota_exceeded
  ├─ Коннекторы перестают принимать вызовы синхронизации
  └─ Сбрасывается в 00:00 UTC 1-го числа следующего месяца

Они совпадают, когда перерасход отключён. С включённым перерасходом жёсткий лимит срабатывает только когда сам кошелёк исчерпан.

Поключевые vs поорганизационные

Это разные вещи:

Достижение rateLimitPerMinute возвращает 429 rate_limit_exceeded (другой код ошибки) и не связано с биллингом. См. Лимиты запросов.

Матрица решений

Прогнозирование следующего месяца

Чтобы оценить, уложитесь ли вы в текущий тариф:

const usage = await admin.getUsage(7); // последние 7 дней
const dailyAvg = usage.rows.reduce((s, r) => s + r.searchUnits, 0) / 7;
const projected30d = dailyAvg * 30;
console.log("прогноз на этот месяц:", projected30d);
console.log("лимит тарифа:", planCap);

Если projected30d приближается к лимиту тарифа, обновите тариф заранее, не дожидаясь алерта.

Диагностический пакет

Связанные страницы

• Тарифы и лимиты — цифры квот по тарифам
• Лимиты запросов — поключевое (не поорганизационное) ограничение
• Ошибки и лимиты запросов — матрица кодов ошибок
• Ошибки аутентификации — для 401/403 (не 429)