# Ошибки

Коды, их распределение и виды ошибок

> Страница сайта MCP Docs — неофициального перевода документации Model Context Protocol (https://mcpdocs.ru/protocol/errors/). Тип: Перевод и пересказ. Основа: Спецификация, разделы «Overview» и «Streamable HTTP»; список изменений (https://modelcontextprotocol.io/specification/2026-07-28/basic/index). Ревизия спецификации 2026-07-28, сверено 05.10.2026.

Ответ с ошибкой — стандартное сообщение JSON-RPC 2.0. В версии 2026-07-28 спецификация ввела политику распределения кодов, чтобы реализации не конфликтовали с кодами протокола.

Как сервер отвечает на неизвестную версию, расхождение заголовков и неизвестный метод, проверяет бесплатная [проверка MCP-сервера](https://mcpprotocol.ru/mcp-check/).

## Структура

```typescript
{
  jsonrpc: "2.0";
  id?: string | number;
  error: { code: number; message: string; data?: unknown; }
}
```

- Ответ с ошибкой ДОЛЖЕН содержать тот же идентификатор, что и запрос (кроме случая, когда идентификатор нельзя прочитать из-за некорректного запроса).
- Код ошибки ДОЛЖЕН быть целым числом.
- `data` МОЖЕТ содержать дополнительные сведения любого типа, например вложенные ошибки.

## Распределение кодов

Для общих сбоев протокола MCP использует стандартные коды JSON-RPC 2.0: `-32700` и от `-32600` до `-32603`. Диапазон от `-32000` до `-32099` JSON-RPC резервирует для реализационных ошибок сервера, и MCP делит его так.

| Диапазон | Статус |
| --- | --- |
| от `-32000` до `-32019` | **Прежние.** Коды, которые реализации выбрали до введения политики. Новые коды в этом поддиапазоне выделять НЕЛЬЗЯ, а новым реализациям их СЛЕДУЕТ не использовать вовсе. Кроме `-32002` (см. ниже), получатель НЕ ДОЛЖЕН предполагать у этих кодов конкретный смысл. |
| от `-32020` до `-32099` | **Зарезервированы для спецификации MCP.** Определяются только ею и записываются в схеме. Реализации НЕ ДОЛЖНЫ выдавать коды из этого диапазона, не определённые спецификацией, и ДОЛЖНЫ использовать определённые только с заданным смыслом. |

Новые коды для других целей СЛЕДУЕТ выделять вне диапазона, зарезервированного JSON-RPC (от `-32768` до `-32000`): остальная часть целых чисел доступна для прикладных ошибок.

## Коды MCP

| Код | Название | Когда возникает |
| --- | --- | --- |
| `-32020` | `HeaderMismatch` | Заголовки HTTP не совпадают со значениями в теле запроса или обязательные заголовки отсутствуют либо искажены. HTTP-статус `400`. |
| `-32021` | `MissingRequiredClientCapability` | Для запроса нужна возможность, которую клиент не объявил. В `data.requiredCapabilities` перечень недостающих. HTTP-статус `400`. |
| `-32022` | `UnsupportedProtocolVersion` | Сервер не поддерживает версию из запроса. В `data` поля `supported` и `requested`. HTTP-статус `400`. |

Пример `UnsupportedProtocolVersionError`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32022,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2026-07-28", "2025-11-25"],
      "requested": "1900-01-01"
    }
  }
}
```

Клиенту СЛЕДУЕТ выбрать из `supported` общую версию и повторить запрос или показать пользователю ошибку, если совместимой версии нет.

## Другие ошибки по умолчанию

| Ситуация | Код и статус HTTP |
| --- | --- |
| В запросе нет обязательного поля `_meta` (версии протокола или возможностей клиента) | `-32602` (неверные параметры), HTTP `400` |
| Сервер не реализует запрошенный метод | `-32601` (метод не найден), HTTP `404` |
| Неизвестный инструмент, некорректный запрос | `-32602` |
| Ресурс не найден | `-32602` (до 2026-07-28 `-32002`) |

## Устаревшие коды

Коды, определённые прежними версиями, остаются зарезервированными и не будут использованы заново. Реализации ревизии 2026-07-28 НЕ ДОЛЖНЫ выдавать эти коды:

- `-32002` — ресурс не найден (2025-11-25 и ранее; заменён на `-32602`). Клиентам СЛЕДУЕТ по-прежнему принимать `-32002` от серверов прежних версий.
- `-32042` — требуется элицитация по URL (только 2025-11-25).

Коды, введённые в черновике этой ревизии, перенумерованы: `HeaderMismatch` из `-32001` в `-32020`, `MissingRequiredClientCapability` из `-32003` в `-32021`, `UnsupportedProtocolVersion` из `-32004` в `-32022`. Ошибка `HeaderMismatchError` добавлена в схему, раньше она существовала только в тексте о транспорте.

Ошибки, которые чисто локальны для реализации (например, таймаут внутри SDK), спецификация пока не кодирует. Реализации, которые показывают такие ошибки в виде структур JSON-RPC, должны сделать так, чтобы их нельзя было принять за ошибки от собеседника.

## Ошибки инструментов

Вызов инструмента различает ошибки протокола (неизвестный инструмент, некорректный запрос, сбой сервера, возвращаются как ошибки JSON-RPC) и ошибки выполнения (сбои API, неверные данные, бизнес-логика, возвращаются в результате с `isError: true`). Подробнее: [«Инструменты»](https://mcpdocs.ru/concepts/tools/#oshibki).