# Лимиты

## Главное для агента

| Лимит | Значение |
| --- | --- |
| Запросов на ключ в минуту | 60 (REST и MCP вместе) |
| Запросов на ключ в сутки | 2000 (сутки UTC) |
| Запросов на студента в сутки | 3000 по всем ключам (сутки UTC) |
| Поиск и транскрипты | дополнительно 20 в минуту на ключ |
| Тело запроса MCP | до 64 KiB, один JSON-RPC объект |

Окна фиксированные. При превышении – `429 RATE_LIMITED`, заголовок `Retry-After` и `error.retryAfterSec` в теле; в MCP вызов инструмента возвращает `isError: true` с тем же кодом. Подождите указанное время и повторите.

## Общие правила

Формат REST: `{ "error": { "code": "VALIDATION_FAILED", "message": "Некорректный запрос", "issues": [{"path":"field","message":"..."}] } }`. [Все коды, HTTP статусы и retry](/docs/errors).

Для любого обработчика возможен `500 INTERNAL`; неизвестный URL – `404 NOT_FOUND`, другой метод на зарегистрированном REST path – `405 METHOD_NOT_ALLOWED`. Для защищённых маршрутов дополнительно действуют проверки middleware: `401 UNAUTHENTICATED`, `403 CREDENTIAL_NOT_ALLOWED` при неподходящем типе credential; при scope – `403 INSUFFICIENT_SCOPE`. Неверные UUID, обрабатываемые `parseParams`, дают 404, а не 422.

Если у маршрута «отдельного throttle нет», это не обещание неограниченного использования, а отсутствие отдельного счётчика в текущем коде. Agent-key/OAuth лимиты REST и MCP общие: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; transcript/search дополнительно 20/min/key. Окна фиксированные, при отказе `429 RATE_LIMITED`, `Retry-After` и `error.retryAfterSec`. Квоты создания ключей, файлов, диктовки и тьютора используют **день МСК**, пауза тьютора `GLOBAL_BUDGET` – **UTC**. Прокси может вернуть собственную ошибку без REST envelope (например, oversized body).

## Лимиты по эндпоинтам

| Эндпоинт | Лимиты |
| --- | --- |
| [`POST /api/v1/auth/link/inspect`](/docs/api/auth/auth-link-inspect) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`POST /api/v1/auth/link/redeem`](/docs/api/auth/auth-link-redeem) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`POST /api/v1/auth/oidc/start`](/docs/api/auth/auth-oidc-start) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`POST /api/v1/auth/oidc`](/docs/api/auth/auth-oidc) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`POST /api/v1/auth/tma`](/docs/api/auth/auth-tma) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`POST /api/v1/auth/tma/refresh`](/docs/api/auth/auth-tma-refresh) | Отдельного throttle в коде нет. |
| [`POST /api/v1/auth/logout`](/docs/api/auth/auth-logout) | Отдельного throttle в коде нет. |
| [`GET /api/v1/auth/sessions`](/docs/api/auth/auth-sessions) | Отдельного throttle в коде нет. |
| [`POST /api/v1/auth/sessions/revoke-all`](/docs/api/auth/auth-sessions-revoke-all) | Отдельного throttle в коде нет. |
| [`POST /api/v1/auth/password/login`](/docs/api/auth/auth-password-login) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`POST /api/v1/auth/password/forgot`](/docs/api/auth/auth-password-forgot) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`POST /api/v1/auth/password/reset`](/docs/api/auth/auth-password-reset) | Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`GET /api/v1/auth/password`](/docs/api/auth/auth-password-status) | Отдельного throttle в коде нет. |
| [`POST /api/v1/auth/password/setup`](/docs/api/auth/auth-password-setup) | 3/10 min/student; защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`. |
| [`POST /api/v1/auth/password/change`](/docs/api/auth/auth-password-change) | 5/10 min/student. |
| [`GET /api/v1/me`](/docs/api/profile/me) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/me/avatar`](/docs/api/profile/me-avatar) | Отдельного throttle в коде нет. |
| [`GET /api/v1/onboarding`](/docs/api/profile/onboarding-get) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`PATCH /api/v1/onboarding`](/docs/api/profile/onboarding-patch) | Отдельного throttle в коде нет. |
| [`PUT /api/v1/onboarding/setup`](/docs/api/profile/onboarding-setup) | Отдельного throttle в коде нет. |
| [`POST /api/v1/onboarding/submit`](/docs/api/profile/onboarding-submit) | Отдельного throttle в коде нет. |
| [`GET /api/v1/plan`](/docs/api/profile/plan-get) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/sections`](/docs/api/content/sections) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/lessons`](/docs/api/content/lessons) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/lessons/{id}`](/docs/api/content/lesson-get) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/lessons/{id}/transcript`](/docs/api/content/lesson-transcript) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key для этого тяжёлого метода. |
| [`GET /api/v1/efirs`](/docs/api/content/efirs) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/next`](/docs/api/content/next) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/search`](/docs/api/content/search) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student; дополнительно 20/min/key для этого тяжёлого метода. |
| [`PUT /api/v1/plan/milestones`](/docs/api/progress/plan-milestones-put) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/progress`](/docs/api/progress/progress-get) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`PUT /api/v1/progress`](/docs/api/progress/progress-put) | Agent-key/OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`POST /api/v1/transcribe`](/docs/api/tutor/transcribe) | 1 запись одновременно; по умолчанию 1800 учитываемых секунд/день МСК; списание ceil(durationSec), минимум 10 секунд за вызов провайдера. |
| [`GET /api/v1/tutor/messages`](/docs/api/tutor/tutor-messages) | Отдельного throttle в коде нет. |
| [`POST /api/v1/tutor/messages`](/docs/api/tutor/tutor-send) | 1 запуск одновременно на студента; сообщения и USD/день МСК из тарифа (`Me.limits`). Общая оценка изображений сообщения ≤10 000 tokens. |
| [`GET /api/v1/tutor/facts`](/docs/api/tutor/tutor-facts) | Отдельного throttle в коде нет. |
| [`DELETE /api/v1/tutor/facts/{id}`](/docs/api/tutor/tutor-fact-delete) | Отдельного throttle в коде нет. |
| [`POST /api/v1/files`](/docs/api/files/files-upload) | параллельные загрузки разрешены. Для PDF – до 2 резерваций на студента суммарно в обработке и ожидании. 20 попыток/день МСК, сброс в 00:00 МСК; отказы после резервирования дневной попытки тоже считаются, кроме отказа из-за занятости сервера: такая попытка возвращается в квоту. Превышение собственных 2 PDF-резерваций попытку расходует. Оба вида занятости дают `429 RATE_LIMITED`, сообщение «Сервер занят, попробуйте через минуту», `retryAfterSec: 60`; исчерпанная дневная квота – `429 DAILY_LIMIT`. Лимит хранения – 200 MiB: все неприкреплённые и прикреплённые за последние 30 суток. |
| [`GET /api/v1/files/{id}`](/docs/api/files/files-get) | Отдельного throttle в коде нет. |
| [`DELETE /api/v1/files/{id}`](/docs/api/files/files-delete) | Отдельного throttle в коде нет. |
| [`GET /api/v1/keys`](/docs/api/keys/keys-list) | Отдельного throttle в коде нет. |
| [`POST /api/v1/keys`](/docs/api/keys/keys-create) | До 3 активных персональных ключей; до 10 созданий за день МСК (включая rotation). |
| [`POST /api/v1/keys/{id}/rotate`](/docs/api/keys/keys-rotate) | Те же ограничения создания: до 3 активных и 10 созданий/день МСК; заменяемый ключ не занимает дополнительный слот. |
| [`DELETE /api/v1/keys/{id}`](/docs/api/keys/keys-revoke) | Отдельного throttle в коде нет. |
| [`GET /api/v1/keys/calls`](/docs/api/keys/keys-calls) | Отдельного throttle в коде нет. |
| [`GET /api/v1/mentoring/track`](/docs/api/mentoring/mentoring-track) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/mentoring/track/versions`](/docs/api/mentoring/mentoring-versions) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/mentoring/sessions`](/docs/api/mentoring/mentoring-sessions) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/mentoring/sessions/{sessionId}`](/docs/api/mentoring/mentoring-session) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/mentoring/decisions`](/docs/api/mentoring/mentoring-decisions) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/mentoring/chat/digests`](/docs/api/mentoring/mentoring-digests) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/mentoring/chat/messages`](/docs/api/mentoring/mentoring-messages) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /api/v1/mentoring/homework`](/docs/api/mentoring/mentoring-homework) | API-ключ / OAuth: 60/min/key, 2000/UTC day/key, 3000/UTC day/student. |
| [`GET /healthz`](/docs/api/ops/healthz) | Отдельного throttle в коде нет. |
