Квоты

Квота — лимит плана за период. AACsearch имеет четыре квоты (search units, индексируемые документы, синхронизации, AI-кошелёк) и три порога на каждую (soft 80%, hard 100%, overage выше 100%). Эта страница описывает поведение гейтов.

Quota gate

Каждый поисковый и ингест-запрос проходит:

Auth         (валидный ключ + org)
  → Feature  (план разрешает операцию)
  → Quota    (есть остаток в периоде)
  → Rate     (лимит запросов ключа не превышен)
  → Search engine

Quota gate вызывает checkQuota(orgId, "search") в packages/api/modules/entitlements/middleware/quota-check.ts. Возвращает одно из:

• allowed: true — пройти.
• allowed: false, reason: "search_quota_exceeded" — 429.
• allowed: true, isSoftCap: true — пройти, но в ответе advisory-заголовок.

Soft caps (80%)

При 80% любой квоты панель показывает предупреждение, а API добавляет advisory-заголовок в каждый ответ:

X-Aacsearch-Quota-Warning: search 82% used; resets 2025-11-01T00:00:00Z

Заголовок информационный — запросы всё ещё успешны. Используйте его для своих алертов (Datadog, Slack-webhook), а не полагайтесь на email из панели.

В панели:

• Оранжевый баннер на /[orgSlug]/overview и /[orgSlug]/settings/billing.
• Плитка квот: 82% used оранжевым.
• Однократный email биллинг-контактам при первом пересечении 80% в периоде.

Hard caps (100%)

При 100% гейт переключается и запросы отклоняются:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "search_quota_exceeded",
  "detail": "Месячная квота поиска исчерпана. Обновите план или дождитесь сброса.",
  "quota": "search",
  "limit": 1000000,
  "used": 1000000,
  "resetsAt": "2025-11-01T00:00:00Z"
}

Что именно блокируется на hard cap, зависит от квоты:

Падения эмитируют SearchUsageEvent с type: "quota_block" — видны в Аналитике → Ошибки.

Overage (выше 100%, только платные)

Платные планы могут включить overage — постоплачиваемая запись потребления выше hard cap, биллится в конце периода. Включается в /settings/billing → Allow overage:

• Запросы выше cap продолжают успешно проходить вместо 429.
• Каждый overage-юнит пишется в OverageTransaction с per-unit ценой (сейчас $0,0001 за search unit на Pro, ниже на Business — точные ставки в packages/payments/lib/entitlements.ts).
• Панель показывает Overage so far this period: $4.32 на /settings/billing.
• В следующий счёт попадает одна строка на каждую квоту с overage.

Overage выключен по умолчанию на Pro и включён на Business. Free и Starter не могут включить overage — всегда hard cap.

Для защиты от runaway-биллов задавайте spending limit организации (/settings/billing → Spending cap). При достижении лимита overage останавливается и возобновляются 429.

Расписание сброса квот

Квоты сбрасываются на первый день биллинг-периода. Большинство клиентов на месячном биллинге; сброс в 00:00:00 UTC 1-го числа. Годовые — на годовщине первого платежа.

Дату следующего сброса видно на /[orgSlug]/settings/billing и в заголовке X-Aacsearch-Quota-Reset любого ответа около cap.

При сбросе:

• Счётчик становится 0.
• Overage из предыдущего периода идёт в счёт ренью — на новый период не влияет.
• Spending caps сбрасываются к настроенному значению.

Без переноса. Неиспользованная квота не переходит в следующий период.

Когда какой cap

По умолчанию:

• Поиски — hard cap 100%. Превышение обычно значит runaway-трафик виджета; видимый 429 — оправдан.
• Индексируемые документы — hard cap 100%. Превышать обычно значит баг коннектора; блокировка ингеста — правильный дефолт.
• Синхронизации коннекторов — soft cap первый месяц после пробоя, затем hard. Даёт окно: либо план поднять, либо интервал растянуть.
• Кошелёк — всегда hard (баланс 0 = нет AI). Soft-режима нет — микро-USD-расход может идти как угодно быстро.

Дефолты — в packages/payments/lib/entitlements.ts. Enterprise может переопределить per-quota контрактом.

Grace-периоды после отмены

После отмены платного плана — полный доступ до конца оплаченного периода. Затем:

• Чтение — ещё 7 дней с лимитами прошлого плана. Это grace на чтение.
• Запись — прекращается в день окончания. Grace нет.

Grace существует, чтобы подписаться заново без потери данных. После 30 дней без оплаты dormant-индексы помечаются на архив, а баланс кошелька сохраняется бессрочно.

Детали: Апгрейд и даунгрейд → Отмена.

Диагностика

При срабатывании квоты смотрите:

1. /[orgSlug]/overview — плитка квот и процент.
2. /[orgSlug]/analytics — пер-дневной чарт показывает, когда был всплеск.
3. /[orgSlug]/analytics → Ошибки — фейлы search_quota_exceeded.
4. Заголовки X-Aacsearch-Quota-* — программная проверка.
5. /admin/wallet (только админ) — история списаний кошелька.

При неожиданном 429 аудит не поможет — quota-блоки не эмитятся в аудит (флудят бы лог). Используйте аналитику.

Заголовки ответа

В каждом успешном ответе:

Используйте их в продакшен-коде вместо опроса панели.

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

• Планы — матрица планов с капами.
• Единицы потребления — что считается за юнит.
• Кошелёк и AI-кредиты — механика квоты кошелька.
• Ошибки и лимиты — каталог HTTP-ошибок 429.
• Планы и лимиты (архитектура) — код прав.