Справка
Ошибки
REST envelope#
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Некорректный запрос",
"issues": [{ "path": "text", "message": "Напишите вопрос" }]
}
}| Поле | Тип | Обязательно | Правило |
|---|---|---|---|
error | object | да | Контейнер ошибки |
error. | string enum | да | Один из кодов таблицы ниже |
error. | string | да | 1–500 символов, безопасный русский текст; конкретный сервис может заменить default |
error. | positive integer | нет | Задержка в секундах; renderer также ставит Retry- |
error. | { | нет | До 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_ | 422 | Некорректный запрос | Исправить поля из issues. Также raw media/type/size, неверный JSON, пустой вопрос или недопустимые вложения. |
ONBOARDING_ | 422 | Анкета заполнена не полностью | Заполнить обязательные ответы анкеты и выбранные варианты «Другое»; повторить submit. |
UNAUTHENTICATED | 401 | Нужно войти в кабинет | Войти заново либо заменить неизвестный, истёкший или отозванный token. Cookie не подменяет явно переданный bearer. |
LOGIN_ | 401 | Не удалось войти через Telegram, попробуйте ещё раз | Повторить вход; для password login текст одинаков для неверной пары и неизвестного email. |
LINK_ | 401 | Ссылка для входа недействительна или устарела. Запросите новую в боте | Запросить новую ссылку. Одноразовый токен уже использован, истёк или недействителен. |
REAUTH_ | 401 | Для этого действия войдите заново | Пройти новый вход. Для управления ключами и revoke-all нужна web-аутентификация ≤10 минут; для первого setup почты – свежий Telegram-вход. |
CREDENTIAL_ | 403 | Это действие доступно только в веб-кабинете | Использовать разрешённый тип credential. Например, ключ агента не может вызывать tutor, transcribe или keys management. |
INSUFFICIENT_ | 403 | Недостаточно прав | Создать ключ/повторно согласовать OAuth с нужным scope. Правильный scope не отменяет ограничение credential type. |
ORIGIN_ | 403 | Запрос отклонён | Передать точный Origin кабинета; при отсутствии Origin допустим Sec-Fetch-Site: same-origin. Для MCP отсутствие Origin разрешено. |
LOGIN_ | 403 | Сессия входа устарела, начните вход заново | Начать Telegram OIDC вход заново: state cookie/запрос отсутствует, отличается или истёк. |
NO_ | 403 | Нет доступа к кабинету | Проверить участие в потоке/блокировку. Login и refresh не должны продолжаться при отрицательном решении. |
MENTORING_ | 403 | Personal mentoring is unavailable | Mentoring reads require personal mentoring on the enrollment (Me. is curator or dashi, whatever the tier), checked within 15 minutes; no outage grace. No student/source metadata is disclosed. |
ONBOARDING_ | 403 | Урок откроется после анкеты | Пройти анкету в кабинете; повторить чтение gated-урока или сохранение его прогресса. |
NOT_ | 404 | Не найдено | Проверить код/id и доступ. Чужой ресурс не раскрывается. OIDC/mail endpoints могут быть выключены; plan/milestones пока не зарегистрирован. |
VERSION_ | 409 | Данные изменились, обновите и повторите | Перечитать актуальные данные, затем повторить с новым expectedVersion. Также возможен конфликт password setup или avatar unchanged. |
BUSY | 409 | Предыдущая запись ещё расшифровывается, подождите | Дождаться текущей операции студента. Используется для dictation и tutor; сообщение зависит от операции. |
METHOD_ | 405 | Метод не поддерживается | Использовать документированный HTTP-метод. Для /mcp разрешён только POST. |
RATE_ | 429 | Слишком много запросов, попробуйте позже | Дождаться retryAfterSec / Retry-After; не запускать цикл мгновенных повторов. Для upload занятость сервера даёт этот код с retryAfterSec=60; серверный отказ возвращает дневную попытку, превышение 2 PDF-резерваций владельца – нет. |
DAILY_ | 429 | Дневной лимит диктовки исчерпан, попробуйте завтра | Дождаться 00:00 МСК. Это секунды диктовки, сообщения/USD тьютора или попытки загрузки файлов; message переопределяется сервисом. |
GLOBAL_ | 429 | Тьютор отдыхает до 03:00 МСК. Попробуйте после этого времени | Тьютор приостановлен для всех до 00:00 UTC (03:00 МСК). Дождаться retryAfterSec. |
KEY_ | 409 | Уже есть 3 активных ключа, отзовите один из них | Уже 3 активных персональных ключа; отозвать один перед созданием. OAuth access keys в эту квоту не входят. |
KEY_ | 429 | Сегодня создано слишком много ключей, попробуйте завтра | Достигнуты 10 созданий персональных ключей за день МСК (rotation тоже создание). Дождаться 00:00 МСК. |
STORAGE_ | 409 | Место для файлов закончилось: до 200 МБ за 30 дней. Удалите неотправленные файлы или подождите, пока старые перестанут учитываться | Все unattached + attached за последние 30 суток занимают 200 MiB. Удалить неприкреплённые файлы или дождаться выхода старых из окна. |
ENTITLEMENT_ | 503 | Не удалось проверить доступ, попробуйте через пару минут | Повторить после Retry-After, если он задан. Read может работать в grace по cached решению; tutor POST в grace не работает. |
DICTATION_ | 503 | Диктовка сейчас недоступна, напишите текстом | Диктовка не настроена или STT недоступен. Написать текстом либо повторить позже. |
TUTOR_ | 503 | Тьютор временно недоступен. Попробуйте чуть позже | Тьютор выключен, провайдер недоступен, превышены внутренние ограничения запуска или невозможно сформировать ответ. Проверить retryAfterSec. |
INTERNAL | 500 | Внутренняя ошибка | Непредвиденная ошибка; детали не возвращаются клиенту. Повторять запись только с её правилом идемпотентности. |
OAuth#
OAuth subrouter использует собственный JSON envelope (строка error, без REST message); браузерные email-формы также возвращают HTML-ошибки, описанные ниже:
{ "error": "invalid_grant" }| Code | HTTP / способ доставки | Причина |
|---|---|---|
invalid_ | 400; authorize также 302 на проверенный callback; body cap 413 | Некорректная/повторяющаяся форма, missing fields, pending cookie/record, CSRF (включая disconnect), PKCE challenge, непроверенный client/redirect |
invalid_ | 400 при DCR | redirect_uris не соответствует allowlist |
invalid_ | 400 при DCR | Другие поля регистрации не проходят схему; grant_ обязательно включает authorization_ |
unsupported_ | 302 authorize callback | response_type отличается от code |
invalid_ | 302 authorize callback / 400 token | resource не совпадает с точным MCP URL; обязателен для code flow |
invalid_ | 302 authorize callback | Неизвестные scopes либо нет ни одного student scope |
access_ | 302 callback / 403 JSON при Origin error | Пользователь отказал или Origin отклонён |
login_ | 401 либо исходный HTTP-статус ApiError | Нет подходящей web-сессии; ApiError внутри OAuth отображаются так (например, 403/503 участия), кроме HTML-ответов verify ниже |
invalid_ | 400 token; 401 form endpoints | На token неизвестен/отсутствует client_id → 400. На token/revoke/email/disconnect предъявлен Authorization или client_secret → 401 |
unauthorized_ | 400 token | Известный клиент не зарегистрировал запрошенный grant (например, refresh для code-only клиента) |
unsupported_ | 400 token | grant_type не authorization_code/refresh_token |
invalid_ | 400 token | Code/refresh истёк, использован, неверен; PKCE/redirect/client/scope не совпали; участие отозвано |
temporarily_ | 429 с Retry-After; 503 DCR / refresh | OAuth throttle; DCR временно не принимает регистрации (503, Retry-After: 300); refresh entitlement outage (503 без Retry-After) |
server_ | 500 | Непредвиденная ошибка OAuth без раскрытия exception/token |
invalid_ | Параметр WWW-Authenticate при HTTP 401 /mcp | Предъявленный MCP token недействителен; отсутствует, если token не был предъявлен |
На authorize ошибки отправляются на callback только после проверки redirect. Callback содержит state (если был) и iss; для [ результат POST consent доставляется через HTML completion page с meta refresh и ссылкой. До проверки redirect ошибка остаётся локальным JSON. Без сессии GET authorize показывает email-вход (200 HTML) и создаёт pending flow; GET connections перенаправляет на login.
Неверный scope на token endpoint – invalid_: разрешено непустое подмножество consented scopes (code) или scopes предъявленного refresh, с хотя бы одним student scope. Порядок и повторы несущественны; повышение прав отклоняется. Сужение access при refresh не сужает новый refresh token. Replay code с правильными client/PKCE/redirect/resource либо использованного refresh отзывает весь grant и выданные tokens, возвращая invalid_.
Email-формы: неверный/истёкший код и исчерпанные 5 попыток дают 400 HTML, без JSON error code. Rate limit на / при синтаксически корректной pending cookie – 429 HTML + Retry-. На verify ApiError, кроме Origin rejection, также дают нейтральную HTML-страницу с исходным статусом (например, 401/403/503), если такая cookie есть; в остальных случаях ApiError отображается как login_.
Discovery живёт вне OAuth subrouter и использует общий обработчик ошибок приложения.
MCP#
До выполнения инструмента MCP может вернуть REST envelope с HTTP 401/403/429/503/500. Если известный tool превысил лимит после распознавания живого ключа, ответ – tool error с RATE_ и retryAfterSec, часто HTTP 200.
Успех транспорта не означает успех инструмента:
{
"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 / причина |
|---|---|---|
- | 400 | Parse error: тело не является JSON |
- | 400 | Batch requests are not supported |
- | 200 | Method not found: subscriptions/listen |
- | 413 | Request body too large: более 64 KiB |
Пример: {. Дополнительно SDK v2 валидирует MCP envelopes/arguments и headers (возможны HTTP 400/406/415 и protocol/tool errors). Этот справочник перечисляет коды, заданные собственным кодом AgentOS; полный набор внутренних диагностик стороннего SDK не является контрактом AgentOS.
GET/DELETE и остальные методы /mcp – 405 METHOD_, Allow:; чужой Origin отклоняется раньше проверки метода. Внутренние ошибки tool не возвращают stack trace. Сообщение ONBOARDING_ направляет студента в /, INSUFFICIENT_ – к созданию ключа с нужным правом.