К содержанию
AgentOSДокументация
  • Загружаем индекс…
llms.txtКабинет

Справка

Ошибки

REST envelope#

json
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Некорректный запрос",
    "issues": [{ "path": "text", "message": "Напишите вопрос" }]
  }
}
ПолеТипОбязательноПравило
errorobjectдаКонтейнер ошибки
error.codestring enumдаОдин из кодов таблицы ниже
error.messagestringда1–500 символов, безопасный русский текст; конкретный сервис может заменить default
error.retryAfterSecpositive 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 кодов.

CodeHTTPDefault messageЧто означает / действие
VALIDATION_FAILED422Некорректный запросИсправить поля из issues. Также raw media/type/size, неверный JSON, пустой вопрос или недопустимые вложения.
ONBOARDING_INCOMPLETE422Анкета заполнена не полностьюЗаполнить обязательные ответы анкеты и выбранные варианты «Другое»; повторить submit.
UNAUTHENTICATED401Нужно войти в кабинетВойти заново либо заменить неизвестный, истёкший или отозванный token. Cookie не подменяет явно переданный bearer.
LOGIN_INVALID401Не удалось войти через Telegram, попробуйте ещё разПовторить вход; для password login текст одинаков для неверной пары и неизвестного email.
LINK_INVALID401Ссылка для входа недействительна или устарела. Запросите новую в ботеЗапросить новую ссылку. Одноразовый токен уже использован, истёк или недействителен.
REAUTH_REQUIRED401Для этого действия войдите зановоПройти новый вход. Для управления ключами и revoke-all нужна web-аутентификация ≤10 минут; для первого setup почты – свежий Telegram-вход.
CREDENTIAL_NOT_ALLOWED403Это действие доступно только в веб-кабинетеИспользовать разрешённый тип credential. Например, ключ агента не может вызывать tutor, transcribe или keys management.
INSUFFICIENT_SCOPE403Недостаточно правСоздать ключ/повторно согласовать OAuth с нужным scope. Правильный scope не отменяет ограничение credential type.
ORIGIN_REJECTED403Запрос отклонёнПередать точный Origin кабинета; при отсутствии Origin допустим Sec-Fetch-Site: same-origin. Для MCP отсутствие Origin разрешено.
LOGIN_STATE_INVALID403Сессия входа устарела, начните вход зановоНачать Telegram OIDC вход заново: state cookie/запрос отсутствует, отличается или истёк.
NO_ENTITLEMENT403Нет доступа к кабинетуПроверить участие в потоке/блокировку. Login и refresh не должны продолжаться при отрицательном решении.
MENTORING_NOT_AVAILABLE403Personal mentoring is unavailableMentoring 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_REQUIRED403Урок откроется после анкетыПройти анкету в кабинете; повторить чтение gated-урока или сохранение его прогресса.
NOT_FOUND404Не найденоПроверить код/id и доступ. Чужой ресурс не раскрывается. OIDC/mail endpoints могут быть выключены; plan/milestones пока не зарегистрирован.
VERSION_CONFLICT409Данные изменились, обновите и повторитеПеречитать актуальные данные, затем повторить с новым expectedVersion. Также возможен конфликт password setup или avatar unchanged.
BUSY409Предыдущая запись ещё расшифровывается, подождитеДождаться текущей операции студента. Используется для dictation и tutor; сообщение зависит от операции.
METHOD_NOT_ALLOWED405Метод не поддерживаетсяИспользовать документированный HTTP-метод. Для /mcp разрешён только POST.
RATE_LIMITED429Слишком много запросов, попробуйте позжеДождаться retryAfterSec / Retry-After; не запускать цикл мгновенных повторов. Для upload занятость сервера даёт этот код с retryAfterSec=60; серверный отказ возвращает дневную попытку, превышение 2 PDF-резерваций владельца – нет.
DAILY_LIMIT429Дневной лимит диктовки исчерпан, попробуйте завтраДождаться 00:00 МСК. Это секунды диктовки, сообщения/USD тьютора или попытки загрузки файлов; message переопределяется сервисом.
GLOBAL_BUDGET429Тьютор отдыхает до 03:00 МСК. Попробуйте после этого времениТьютор приостановлен для всех до 00:00 UTC (03:00 МСК). Дождаться retryAfterSec.
KEY_LIMIT409Уже есть 3 активных ключа, отзовите один из нихУже 3 активных персональных ключа; отозвать один перед созданием. OAuth access keys в эту квоту не входят.
KEY_RATE429Сегодня создано слишком много ключей, попробуйте завтраДостигнуты 10 созданий персональных ключей за день МСК (rotation тоже создание). Дождаться 00:00 МСК.
STORAGE_LIMIT409Место для файлов закончилось: до 200 МБ за 30 дней. Удалите неотправленные файлы или подождите, пока старые перестанут учитыватьсяВсе unattached + attached за последние 30 суток занимают 200 MiB. Удалить неприкреплённые файлы или дождаться выхода старых из окна.
ENTITLEMENT_UNAVAILABLE503Не удалось проверить доступ, попробуйте через пару минутПовторить после Retry-After, если он задан. Read может работать в grace по cached решению; tutor POST в grace не работает.
DICTATION_UNAVAILABLE503Диктовка сейчас недоступна, напишите текстомДиктовка не настроена или STT недоступен. Написать текстом либо повторить позже.
TUTOR_UNAVAILABLE503Тьютор временно недоступен. Попробуйте чуть позжеТьютор выключен, провайдер недоступен, превышены внутренние ограничения запуска или невозможно сформировать ответ. Проверить retryAfterSec.
INTERNAL500Внутренняя ошибкаНепредвиденная ошибка; детали не возвращаются клиенту. Повторять запись только с её правилом идемпотентности.

OAuth#

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

json
{ "error": "invalid_grant" }
CodeHTTP / способ доставкиПричина
invalid_request400; authorize также 302 на проверенный callback; body cap 413Некорректная/повторяющаяся форма, missing fields, pending cookie/record, CSRF (включая disconnect), PKCE challenge, непроверенный client/redirect
invalid_redirect_uri400 при DCRredirect_uris не соответствует allowlist
invalid_client_metadata400 при DCRДругие поля регистрации не проходят схему; grant_types обязательно включает authorization_code
unsupported_response_type302 authorize callbackresponse_type отличается от code
invalid_target302 authorize callback / 400 tokenresource не совпадает с точным MCP URL; обязателен для code flow
invalid_scope302 authorize callbackНеизвестные scopes либо нет ни одного student scope
access_denied302 callback / 403 JSON при Origin errorПользователь отказал или Origin отклонён
login_required401 либо исходный HTTP-статус ApiErrorНет подходящей web-сессии; ApiError внутри OAuth отображаются так (например, 403/503 участия), кроме HTML-ответов verify ниже
invalid_client400 token; 401 form endpointsНа token неизвестен/отсутствует client_id → 400. На token/revoke/email/disconnect предъявлен Authorization или client_secret → 401
unauthorized_client400 tokenИзвестный клиент не зарегистрировал запрошенный grant (например, refresh для code-only клиента)
unsupported_grant_type400 tokengrant_type не authorization_code/refresh_token
invalid_grant400 tokenCode/refresh истёк, использован, неверен; PKCE/redirect/client/scope не совпали; участие отозвано
temporarily_unavailable429 с Retry-After; 503 DCR / refreshOAuth throttle; DCR временно не принимает регистрации (503, Retry-After: 300); refresh entitlement outage (503 без Retry-After)
server_error500Непредвиденная ошибка 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 codeHTTPMessage / причина
-32700400Parse error: тело не является JSON
-32600400Batch requests are not supported
-32601200Method not found: subscriptions/listen
-32000413Request 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 – к созданию ключа с нужным правом.