# Ошибки

## REST envelope

```json
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Некорректный запрос",
    "issues": [{ "path": "text", "message": "Напишите вопрос" }]
  }
}
```

| Поле                  | Тип                              | Обязательно | Правило                                                                            |
| --------------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------------------- |
| `error`               | object                           | да          | Контейнер ошибки                                                                   |
| `error.code`          | string enum                      | да          | Один из кодов таблицы ниже                                                         |
| `error.message`       | string                           | да          | 1–500 символов, безопасный русский текст; конкретный сервис может заменить default |
| `error.retryAfterSec` | positive integer                 | нет         | Задержка в секундах; renderer также ставит `Retry-After`                           |
| `error.issues`        | `{path:string,message:string}[]` | нет         | До 50 проблем, path через точку; сообщения Zod могут быть на английском            |

Статус определяется кодом, а не текстом. По `message` нельзя строить ветвление клиента. При наличии retry-поля доверяйте ему, а не фиксированной паузе. Если поля нет, это не обещание, что повтор сразу разрешён. Неверный JSON – 422, а неверный UUID в большинстве resource paths – 404. Internal oversized body – 422; OAuth/MCP используют отдельные 413 форматы.

## Все REST error codes

Ниже **26** кодов.

| Code                      | HTTP | Default message                                                                                                                    | Что означает / действие                                                                                                                                      |
| ------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `VALIDATION_FAILED`       | 422  | Некорректный запрос                                                                                                                | Исправить поля из issues. Также raw media/type/size, неверный JSON, пустой вопрос или недопустимые вложения.                                                 |
| `ONBOARDING_INCOMPLETE`   | 422  | Анкета заполнена не полностью                                                                                                      | Заполнить обязательные ответы анкеты и выбранные варианты «Другое»; повторить submit.                                                                        |
| `UNAUTHENTICATED`         | 401  | Нужно войти в кабинет                                                                                                              | Войти заново либо заменить неизвестный, истёкший или отозванный token. Cookie не подменяет явно переданный bearer.                                           |
| `LOGIN_INVALID`           | 401  | Не удалось войти через Telegram, попробуйте ещё раз                                                                                | Повторить вход; для password login текст одинаков для неверной пары и неизвестного email.                                                                    |
| `LINK_INVALID`            | 401  | Ссылка для входа недействительна или устарела. Запросите новую в боте                                                              | Запросить новую ссылку. Одноразовый токен уже использован, истёк или недействителен.                                                                         |
| `REAUTH_REQUIRED`         | 401  | Для этого действия войдите заново                                                                                                  | Пройти новый вход. Для управления ключами и revoke-all нужна web-аутентификация ≤10 минут; для первого setup почты – свежий Telegram-вход.                   |
| `CREDENTIAL_NOT_ALLOWED`  | 403  | Это действие доступно только в веб-кабинете                                                                                        | Использовать разрешённый тип credential. Например, ключ агента не может вызывать tutor, transcribe или keys management.                                      |
| `INSUFFICIENT_SCOPE`      | 403  | Недостаточно прав                                                                                                                  | Создать ключ/повторно согласовать OAuth с нужным scope. Правильный scope не отменяет ограничение credential type.                                            |
| `ORIGIN_REJECTED`         | 403  | Запрос отклонён                                                                                                                    | Передать точный Origin кабинета; при отсутствии Origin допустим Sec-Fetch-Site: same-origin. Для MCP отсутствие Origin разрешено.                            |
| `LOGIN_STATE_INVALID`     | 403  | Сессия входа устарела, начните вход заново                                                                                         | Начать Telegram OIDC вход заново: state cookie/запрос отсутствует, отличается или истёк.                                                                     |
| `NO_ENTITLEMENT`          | 403  | Нет доступа к кабинету                                                                                                             | Проверить участие в потоке/блокировку. Login и refresh не должны продолжаться при отрицательном решении.                                                     |
| `MENTORING_NOT_AVAILABLE` | 403 | Personal mentoring is unavailable | Mentoring reads require personal mentoring on the enrollment (`Me.mentoring` is `curator` or `dashi`, whatever the tier), checked within 15 minutes; no outage grace. No student/source metadata is disclosed. |
| `ONBOARDING_REQUIRED`     | 403  | Урок откроется после анкеты                                                                                                        | Пройти анкету в кабинете; повторить чтение gated-урока или сохранение его прогресса.                                                                         |
| `NOT_FOUND`               | 404  | Не найдено                                                                                                                         | Проверить код/id и доступ. Чужой ресурс не раскрывается. OIDC/mail endpoints могут быть выключены; plan/milestones пока не зарегистрирован.                  |
| `VERSION_CONFLICT`        | 409  | Данные изменились, обновите и повторите                                                                                            | Перечитать актуальные данные, затем повторить с новым `expectedVersion`. Также возможен конфликт password setup или avatar unchanged. |
| `BUSY`                    | 409  | Предыдущая запись ещё расшифровывается, подождите                                                                                  | Дождаться текущей операции студента. Используется для dictation и tutor; сообщение зависит от операции.                                              |
| `METHOD_NOT_ALLOWED`      | 405  | Метод не поддерживается                                                                                                            | Использовать документированный HTTP-метод. Для /mcp разрешён только POST.                                                                                    |
| `RATE_LIMITED`            | 429  | Слишком много запросов, попробуйте позже                                                                                           | Дождаться retryAfterSec / Retry-After; не запускать цикл мгновенных повторов. Для upload занятость сервера даёт этот код с retryAfterSec=60; серверный отказ возвращает дневную попытку, превышение 2 PDF-резерваций владельца – нет.                                                                                |
| `DAILY_LIMIT`             | 429  | Дневной лимит диктовки исчерпан, попробуйте завтра                                                                                 | Дождаться 00:00 МСК. Это секунды диктовки, сообщения/USD тьютора или попытки загрузки файлов; message переопределяется сервисом.                             |
| `GLOBAL_BUDGET`           | 429  | Тьютор отдыхает до 03:00 МСК. Попробуйте после этого времени                                                                       | Тьютор приостановлен для всех до 00:00 UTC (03:00 МСК). Дождаться retryAfterSec.                                                                             |
| `KEY_LIMIT`               | 409  | Уже есть 3 активных ключа, отзовите один из них                                                                                    | Уже 3 активных персональных ключа; отозвать один перед созданием. OAuth access keys в эту квоту не входят.                                                   |
| `KEY_RATE`                | 429  | Сегодня создано слишком много ключей, попробуйте завтра                                                                            | Достигнуты 10 созданий персональных ключей за день МСК (rotation тоже создание). Дождаться 00:00 МСК.                                                        |
| `STORAGE_LIMIT`           | 409  | Место для файлов закончилось: до 200 МБ за 30 дней. Удалите неотправленные файлы или подождите, пока старые перестанут учитываться | Все unattached + attached за последние 30 суток занимают 200 MiB. Удалить неприкреплённые файлы или дождаться выхода старых из окна.                         |
| `ENTITLEMENT_UNAVAILABLE` | 503  | Не удалось проверить доступ, попробуйте через пару минут                                                                           | Повторить после Retry-After, если он задан. Read может работать в grace по cached решению; tutor POST в grace не работает.                                   |
| `DICTATION_UNAVAILABLE`   | 503  | Диктовка сейчас недоступна, напишите текстом                                                                                       | Диктовка не настроена или STT недоступен. Написать текстом либо повторить позже.                                                                             |
| `TUTOR_UNAVAILABLE`       | 503  | Тьютор временно недоступен. Попробуйте чуть позже                                                                                  | Тьютор выключен, провайдер недоступен, превышены внутренние ограничения запуска или невозможно сформировать ответ. Проверить retryAfterSec.                  |
| `INTERNAL`                | 500  | Внутренняя ошибка                                                                                                                  | Непредвиденная ошибка; детали не возвращаются клиенту. Повторять запись только с её правилом идемпотентности.                                                |

## OAuth

OAuth subrouter использует собственный JSON envelope (строка `error`, без REST `message`); браузерные email-формы также возвращают HTML-ошибки, описанные ниже:

```json
{ "error": "invalid_grant" }
```

| Code                        | HTTP / способ доставки                                         | Причина                                                                                                      |
| --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `invalid_request` | 400; authorize также 302 на проверенный callback; body cap 413 | Некорректная/повторяющаяся форма, missing fields, pending cookie/record, CSRF (включая disconnect), PKCE challenge, непроверенный client/redirect |
| `invalid_redirect_uri`      | 400 при DCR                                                    | redirect_uris не соответствует allowlist                                                                     |
| `invalid_client_metadata` | 400 при DCR | Другие поля регистрации не проходят схему; `grant_types` обязательно включает `authorization_code` |
| `unsupported_response_type` | 302 authorize callback                                         | response_type отличается от code                                                                             |
| `invalid_target`            | 302 authorize callback / 400 token                             | resource не совпадает с точным MCP URL; обязателен для code flow                                             |
| `invalid_scope`             | 302 authorize callback                                         | Неизвестные scopes либо нет ни одного student scope                                                          |
| `access_denied`             | 302 callback / 403 JSON при Origin error                       | Пользователь отказал или Origin отклонён                                                                     |
| `login_required`            | 401 либо исходный HTTP-статус ApiError                         | Нет подходящей web-сессии; ApiError внутри OAuth отображаются так (например, 403/503 участия), кроме HTML-ответов verify ниже |
| `invalid_client` | 400 token; 401 form endpoints | На token неизвестен/отсутствует client_id → 400. На token/revoke/email/disconnect предъявлен Authorization или client_secret → 401 |
| `unauthorized_client` | 400 token | Известный клиент не зарегистрировал запрошенный grant (например, refresh для code-only клиента) |
| `unsupported_grant_type`    | 400 token                                                      | grant_type не authorization_code/refresh_token                                                               |
| `invalid_grant`             | 400 token                                                      | Code/refresh истёк, использован, неверен; PKCE/redirect/client/scope не совпали; участие отозвано            |
| `temporarily_unavailable` | 429 с Retry-After; 503 DCR / refresh | OAuth throttle; DCR временно не принимает регистрации (503, Retry-After: 300); refresh entitlement outage (503 без Retry-After) |
| `server_error`              | 500                                                            | Непредвиденная ошибка OAuth без раскрытия exception/token                                                    |
| `invalid_token`             | Параметр WWW-Authenticate при HTTP 401 /mcp                    | Предъявленный MCP token недействителен; отсутствует, если token не был предъявлен                            |

На authorize ошибки отправляются на callback **только после проверки redirect**. Callback содержит `state` (если был) и `iss`; для `[::1]` результат POST consent доставляется через HTML completion page с meta refresh и ссылкой. До проверки redirect ошибка остаётся локальным JSON. Без сессии GET authorize показывает email-вход (200 HTML) и создаёт pending flow; GET connections перенаправляет на login.

Неверный scope на token endpoint – `invalid_grant`: разрешено непустое подмножество consented scopes (code) или scopes предъявленного refresh, с хотя бы одним student scope. Порядок и повторы несущественны; повышение прав отклоняется. Сужение access при refresh не сужает новый refresh token. Replay code с правильными client/PKCE/redirect/resource либо использованного refresh отзывает весь grant и выданные tokens, возвращая `invalid_grant`.

Email-формы: неверный/истёкший код и исчерпанные 5 попыток дают **400 HTML**, без JSON error code. Rate limit на `/oauth/email/*` при синтаксически корректной pending cookie – **429 HTML** + `Retry-After`. На verify ApiError, кроме Origin rejection, также дают нейтральную HTML-страницу с исходным статусом (например, 401/403/503), если такая cookie есть; в остальных случаях ApiError отображается как `login_required`.

Discovery живёт вне OAuth subrouter и использует общий обработчик ошибок приложения.

## MCP

До выполнения инструмента MCP может вернуть REST envelope с HTTP 401/403/429/503/500. Если известный tool превысил лимит после распознавания живого ключа, ответ – tool error с `RATE_LIMITED` и `retryAfterSec`, часто HTTP 200.

Успех транспорта не означает успех инструмента:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "{\"error\":{\"code\":\"INSUFFICIENT_SCOPE\",\"message\":\"Недостаточно прав\"}}"
      }
    ]
  }
}
```

Ошибки HTTP-адаптера JSON-RPC:

| JSON-RPC code | HTTP | Message / причина                      |
| ------------- | ---- | -------------------------------------- |
| `-32700`      | 400  | Parse error: тело не является JSON     |
| `-32600`      | 400  | Batch requests are not supported       |
| `-32601`      | 200  | Method not found: subscriptions/listen |
| `-32000`      | 413  | Request body too large: более 64 KiB   |

Пример: `{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}`. Дополнительно SDK v2 валидирует MCP envelopes/arguments и headers (возможны HTTP 400/406/415 и protocol/tool errors). Этот справочник перечисляет коды, заданные собственным кодом AgentOS; полный набор внутренних диагностик стороннего SDK не является контрактом AgentOS.

GET/DELETE и остальные методы /mcp – 405 `METHOD_NOT_ALLOWED`, `Allow: POST`; чужой Origin отклоняется раньше проверки метода. Внутренние ошибки tool не возвращают stack trace. Сообщение `ONBOARDING_REQUIRED` направляет студента в `/#/onboarding`, `INSUFFICIENT_SCOPE` – к созданию ключа с нужным правом.
