Ошибки
Ошибки бывают трёх видов: HTTP-коды транспорта, ошибки протокола MCP и ошибки самого инструмента. Пустой результат («Не знаю») ошибкой не является, см. Правила и ограничения.
HTTP-коды#
Тело ответа при ошибке — JSON вида {"error": "<текст>"}.
| Код | Тело | Причина | Что делать |
|---|---|---|---|
400 | bad JSON | тело запроса не JSON | отправьте корректный JSON-RPC запрос |
401 | invalid key | ключ не передан, неверный, отозван или выключен, либо тенант выключен. Причины намеренно неразличимы | проверьте заголовок Authorization: Bearer <ключ> и отсутствие лишних пробелов; если всё верно, запросите у администратора новый ключ |
403 | origin not allowed | в запросе есть заголовок Origin. Сервис предназначен для серверных клиентов, не для браузера | вызывайте сервис с сервера, а не из браузерного кода |
403 | (иное) | запрос не допущен на входе | обратитесь к администратору |
404 | not found | путь не /mcp или /health, либо в адресе есть query-строка (?…) | используйте точный адрес https://twins.sims-service.com/mcp без параметров |
405 | method not allowed | метод не POST (GET и DELETE не поддерживаются, заголовок Allow: POST) | отправляйте POST |
413 | body too large | тело запроса больше 64 КБ | сократите запрос |
421 | unexpected host | заголовок Host не совпадает с адресом сервиса | обращайтесь по адресу twins.sims-service.com |
429 | rate limit | превышена частота вызовов ключа (по умолчанию 60 в минуту) | подождите Retry-After секунд и повторите |
429 | busy | сервер занят: 8 одновременных вызовов | повторите через секунду (Retry-After: 1) |
500 | internal error | внутренняя ошибка | повторите позже; если не проходит, сообщите администратору время запроса и инструмент |
503 | unavailable | данные тенанта временно недоступны | повторите через несколько минут; если не проходит, обратитесь к администратору |
504 | timeout | вызов не уложился в 10 секунд | сузьте запрос (limit, context, area) и повторите |
При 429 и 504 не повторяйте запрос немедленно в цикле: используйте паузу с нарастанием (backoff). Запросы чтения идемпотентны, повтор безопасен.
Заголовок Retry-After содержит число секунд.
Дополнительно: если клиент не передал Accept: application/json, text/event-stream или Content-Type: application/json, транспорт MCP отвечает ошибкой протокола (обычно 406 или 415). Эти заголовки стандартные MCP-клиенты отправляют сами.
Ошибки протокола MCP#
Неверное имя инструмента или аргументы, не прошедшие проверку схемы (строка длиннее лимита, значение вне перечисления, limit вне диапазона, лишний тип), возвращаются как JSON-RPC ошибка или как результат с isError: true и текстом причины. Исправьте запрос по таблицам аргументов из раздела Инструменты.
Ошибки инструментов#
Результат с isError: true означает нарушение формата входа. Основной случай:
| Текст | Причина | Что делать |
|---|---|---|
invalid cursor | курсор повреждён, выдан для других фильтров или не от этого инструмента | начните с первой страницы без cursor. Не меняйте фильтры между страницами и не собирайте курсор вручную |
Курсор чужого тенанта в twins_changes_since ошибкой не считается: ответ пуст, nohit_reason: "out_of_scope".
Что приходит штатно, но похоже на ошибку#
| Симптом | Объяснение |
|---|---|
пустой список и nohit_reason | нет подходящих утверждений, см. таблицу причин в Правилах. Это ответ «Не знаю» |
verdict: "refused" | вопрос о человеке. Переформулируйте вопрос о роли или шаге |
роль null, small_role: true | роль меньше порога k, возвращена очередь |
has_more: true | ответ обрезан по лимиту страницы или размера (64 КБ); возьмите next_cursor |
reset: true в twins_changes_since | ваш курсор старше хранимой ленты; перечитайте состояние с начала |
unavailable в twins_resolve | утверждение не выдаётся (оспорено, отозвано, чужое или неизвестное); не показывайте и не публикуйте его |
Проверка работоспособности#
GET https://twins.sims-service.com/health не требует ключа и возвращает 200 с {"status":"ok","contract":"0"}. Если /health отвечает, а /mcp нет, проблема в ключе, заголовках или лимитах из таблицы выше. Если не отвечает /health, сервис недоступен, обратитесь к администратору.