Ошибки

Формат

Ошибка — это всегда JSON. Минимальный вид:

{
  "statusCode": 404,
  "message": "Документ не найден",
  "error": "Not Found"
}

message написан по-русски и предназначен человеку: его можно показать в интерфейсе как есть. Внутренних подробностей — путей, SQL, стека — в ответе нет никогда; они остаются в журнале сервера.

Ошибка проверки тела запроса дополнительно перечисляет поля:

{
  "message": "Назовите токен — потом не разберётесь",
  "errors": [
    { "field": "name", "message": "Назовите токен — потом не разберётесь" }
  ]
}

• errors[].field — путь к полю через точку, например data.name или rows.3.1.
• errors[].message — что именно не так.
• message — сводка: до трёх разных причин через точку с запятой, дальше «— и ещё N». Длинное перечисление никто не дочитывает.

Ответы с дополнительными полями — проверка полей, конфликт версии листа, превышение частоты, сбой превью — приходят без statusCode и error: в теле только message и свои поля. Поэтому код ошибки берите из статуса HTTP, а не из тела.

Коды

Конфликт версии листа

У листа есть номер версии version — он растёт с каждым сохранением. Правка листа (PATCH …/sheets/{sheetId}, PATCH …/sheets/{sheetId}/elements, инструменты MCP edit_layout и set_layout) принимает необязательный baseVersion — версию, которую программа видела. Если лист за это время изменился, ответ 409, и в теле есть текущая версия:

{
  "message": "Лист изменился (версия 8, а правка сделана к версии 7). Перечитайте лист и повторите правку.",
  "version": 8
}

Перечитайте лист (GET /api/documents/{id} или get_document), примените правку к свежему листу и передайте baseVersion: 8. Без baseVersion последнее сохранение выигрывает. Редактор в кабинете пишет с версией: чужую правку он не затирает, а спрашивает человека, чья версия остаётся.

Если лист правят одновременно слишком часто и правка четыре раза подряд не застала его неизменным, ответ тоже 409, без version: «Лист правят одновременно слишком часто — повторите запрос». Так бывает и у правок без baseVersion, например у готовой раскладки.

Проверка подлинности — своя форма ответа

Публичная проверка подлинности GET /api/v1/verify/{id} отвечает на ненайденный документ телом другой формы — без statusCode и error, зато с полем reason:

{ "message": "Такого документа нет", "reason": "checksum" }

reason принимает значения malformed (код не той длины или с посторонними знаками), checksum (опечатка — контрольная часть кода не сошлась) и unknown (код правильный, но такого документа нет). Различие нужно, чтобы сказать проверяющему «проверьте, не ошиблись ли при наборе» вместо «документа не существует».

Ошибки входа через OAuth

Адреса OAuth (POST /api/oauth/register, POST /api/oauth/token) разбирают клиенты OAuth, а не люди, поэтому отвечают в формате RFC 6749 — полями error и error_description, без statusCode:

{
  "error": "invalid_grant",
  "error_description": "Код неверный, просрочен или уже использован"
}

Страница согласия https://vruchay.ru/oauth/authorize показывает ошибки человеку по-русски: «Неизвестное приложение: client_id не наш или повреждён», «Адрес возврата не совпадает с зарегистрированным у приложения», «Нужны права управляющего». Отказ человека возвращает приложению error=access_denied в адресе возврата.

Сервер MCP без токена или с неизвестным токеном отвечает 401 с телом {"error": "unauthorized", "message": "…"} и заголовком WWW-Authenticate: Bearer resource_metadata="https://vruchay.ru/.well-known/oauth-protected-resource/mcp" (с неизвестным токеном — ещё error="invalid_token"): по нему клиент начинает вход.

Ошибки в MCP

Ошибка инструмента — это не ошибка протокола. Запрос к /mcp отвечает 200, а в результате вызова стоит isError: true и текст по-русски — тот же, что вернул бы REST:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Ошибка 400: Введите название\nПоля: [{\"field\":\"title\",\"message\":\"Введите название\"}]"
      }
    ]
  }
}

Так агент видит причину и может поправить запрос, а не обрывает работу. Аргументы, не подошедшие схеме инструмента, — тоже isError с текстом «Аргументы не подошли — …».

Ошибкой протокола JSON-RPC (error вместо result) отвечают только на неверное сообщение: -32600 — не JSON-RPC 2.0 или пачка сообщений (и превышение 300 запросов в минуту, вместе с HTTP 429 и Retry-After), -32601 — неизвестный метод, -32602 — неизвестный инструмент или подсказка либо arguments не объект. Клиенты протокола 2026-07-28 получают ещё -32020 (заголовки MCP-Protocol-Version, Mcp-Method, Mcp-Name не совпали с телом, HTTP 400) и -32022 (незнакомая версия, HTTP 400, в data.supported — версии сервера), а неизвестный метод у них — HTTP 404. Подробно — в `POST /mcp`.

Почему 404, а не 403

Обращение к объекту чужой организации отвечает 404. Ответ 403 подтвердил бы, что объект с таким идентификатором существует, — а это уже сведения о чужих делах. Поэтому «не ваш» и «не существует» для API неразличимы.

Разбор ошибок в программе

Ориентируйтесь на статус HTTP и на errors[].field. Тексты сообщений живут в схемах проверки и меняются вместе с ними: сопоставлять их построчно — способ однажды сломаться на исправленной опечатке.

Ошибки с кодами 4xx повторять бессмысленно, пока не изменился запрос. Повторять стоит 429 (после паузы) и 500 (с нарастающей задержкой).