Skip to content

Ошибки и состояния ​

Единица отказа — инструмент, а не сервер. Сервер выключается целиком только тогда, когда он физически недоступен.

Ошибки ​

Ошибка — структурированный объект. Сервер выставляет code, а сторону (side) назначает платформа по таблице ниже; пришедшее от сервера значение side перезаписывается. Тексты для пользователя по паре «код + сторона» в контракт не входят: они на стороне приложения.

Error ​

Ошибка. Структурированный отказ: код из словаря, сторона, пояснение для разработчика и отчёт о нарушениях.

ПолеОбязательноТипЗачем
codeдаErrorCodeЧто случилось: по коду решают, что делать дальше.
messageнетstringПояснение для разработчика.
reportнетсписок ViolationЧто именно в ответе не совпало с контрактом.
sideнетSideЧья это ошибка: кому её чинить.
Код ошибкиСторона
contract_violationbusiness_mcp
tool_excludedbusiness_mcp
tool_outdated_for_agentbusiness_mcp
contract_version_unsupportednorm_platform
no_databusiness_data
stalebusiness_data
unauthorized_scopenorm_rights
tenant_mismatchnorm_rights
gateway_errornorm_platform
transform_errornorm_platform
invalid_principalnorm_platform
invalid_inputagent
not_readybusiness_data
schema_unavailablebusiness_data
record_deletedbusiness_data
record_rejectedbusiness_data
temporarybusiness_data
rate_limitedbusiness_data
unknown_useragent
unknown_fieldagent
business_errorbusiness_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Есть ли смысл повторить вызов позже.

Состояния инструмента ​

Платформа проверяет каждый инструмент сервера по слепку и присваивает ему состояние. Модель видит только инструменты в состоянии active и degraded.

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Кому чинить, если с инструментом что-то не так.