Тема
Ошибки и состояния
Единица отказа — инструмент, а не сервер. Состояние всего сервера разом меняется только тогда, когда он физически недоступен.
Ошибки
Ошибка — структурированный объект. Сервер выставляет code, а сторону (side) назначает платформа по таблице ниже; пришедшее от сервера значение side перезаписывается. Тексты для пользователя по паре «код + сторона» в контракт не входят: они на стороне приложения.
Error
Ошибка. Структурированный отказ: код из словаря, сторона, пояснение для разработчика и отчёт о нарушениях.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
code | да | ErrorCode | Что случилось: по коду решают, что делать дальше. |
message | нет | string | Пояснение для разработчика. |
report | нет | список Violation | Что именно в ответе не совпало с контрактом. |
side | нет | Side | Чья это ошибка: кому её чинить. |
| Код ошибки | Сторона |
|---|---|
contract_violation | business_mcp |
tool_excluded | business_mcp |
tool_outdated_for_agent | business_mcp |
contract_version_unsupported | norm_platform |
no_data | business_data |
stale | business_data |
unauthorized_scope | norm_rights |
tenant_mismatch | norm_rights |
gateway_error | norm_platform |
transform_error | norm_platform |
invalid_principal | norm_platform |
invalid_input | agent |
not_ready | business_data |
schema_unavailable | business_data |
record_deleted | business_data |
record_rejected | business_data |
temporary | business_data |
rate_limited | business_data |
unknown_user | agent |
unknown_field | agent |
business_error | business_mcp |
Side
Сторона. Кто виноват: MCP бизнеса, данные бизнеса, права NORM, платформа NORM, агент.
Значения: business_mcp, business_data, norm_rights, norm_platform, agent.
Violation
Нарушение. Путь JSON Pointer до места расхождения, ожидание и факт.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
actual | да | string | Что там пришло на самом деле. |
expected | да | string | Что там должно быть по контракту. |
path | да | string | Где в ответе расхождение. |
Доменные состояния
Если инструмент не может выполнить запрос по предметной причине — данных ещё нет, запись отклонена, получатель неизвестен, — он отвечает успешно, но кладёт в data.error доменное состояние. Поля данных с пометкой «при успехе» в таком ответе не обязательны.
DomainError
Доменное состояние. Код из словаря контракта, пояснение для разработчика, признак осмысленности повтора и, для неизвестной цели, список допустимых ярлыков.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
code | да | ErrorCode | Что мешает выдать данные: по коду решают, что делать дальше. |
allowed_targets | нет | список string | Какие значения сервер принял бы вместо отвергнутого. |
message | нет | string | Пояснение для разработчика. |
retryable | нет | boolean | Есть ли смысл повторить вызов позже. |
Состояния инструмента
Платформа проверяет каждый инструмент сервера по слепку и присваивает ему состояние. Контракт задаёт только вердикт. Что платформа делает с инструментом в каждом состоянии, описывает документация Gateway.
ToolState
Состояние инструмента. active — работает, degraded — работает с оговоркой, excluded — не соответствует контракту, unavailable — сервер недоступен.
Значения: active, degraded, excluded, unavailable.
ReasonCode
Код причины. Почему инструмент не активен. missing_version — информационная: состояние остаётся active.
Значения: input_schema_violation, output_schema_violation, result_too_large, missing_pagination, unknown_catalog_tool, unknown_contract_version, deprecated, server_unreachable, missing_version.
Проверка соответствия
Итог проверки сервера — отчёт о соответствии. Одна и та же форма у платформы, у утилиты проверки norm-contract check и в админке.
ConformanceReport
Отчёт о соответствии. Какой пакет проверял, когда, и что вышло по каждому инструменту сервера.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
checked_at | да | string (date-time) | Когда проверяли. |
package_version | да | string | Какой версией пакета контракта проверяли. |
server_id | да | string | Какой сервер проверен. |
tools | да | список ToolReport | Итог по каждому инструменту сервера. |
server_version | нет | integer | Какую версию контракта заявил сервер. |
ToolReport
Состояние инструмента. Имя, разрешённые версии, состояние, причины, сторона и подробности расхождений.
| Поле | Обязательно | Тип | Зачем |
|---|---|---|---|
name | да | string | Какой инструмент проверен. |
reasons | да | список ReasonCode | Почему у инструмента такое состояние. |
state | да | ToolState | Можно ли вызывать инструмент. |
versions | да | список integer | Какие версии контракта инструмент поддерживает. |
details | нет | список Violation | Что именно не совпало с контрактом. |
side | нет | Side | Кому чинить, если с инструментом что-то не так. |