Ошибки и восстановление
Один структурированный контракт для REST, MCP и SDK.
Смотрите код, а не английскую формулировку
Ошибки REST используют application/problem+json. Основные поля: status, code, title, detail, request_id, retryable; необязательные — retry_after_seconds и данные действия, например billing_url. В HTTP-заголовках есть ID для поддержки и задержка повтора, когда она применима.
В MCP сбой инструмента возвращает isError:true и structuredContent.error с той же семантикой. HTTP 200 транспорта MCP не гарантирует успех инструмента. Ошибка протокола JSON-RPC отличается от химического результата.
| Код или класс | Что делать |
|---|---|
| Авторизация или отсутствие прав | Войти, выбрать доступное пространство или заменить отозванный ключ |
validation_error / HTTP 422 | Исправить схему, SMILES, формат или параметр |
not_found, tool_not_found | Использовать возвращённый ID или поддерживаемое действие |
credits_exhausted | Проверить рабочую квоту и баланс пространства |
sandbox_quota_exhausted | Исчерпана тестовая квота, отдельная от рабочего кредита |
workspace_limit_reached, key_limit_reached | Проверить правило и настоящее время сброса |
request_rate_limited | Соблюдать указанную короткую задержку |
| Недоступность или тайм-аут источника | Повторять только при retryable; сохранить ID запроса |
SDK сохраняет неизвестные будущие коды: текущий перечень не считается исчерпывающим. Логика должна опираться на стабильный code; title и detail — поясняющий текст, который может меняться или локализоваться.
Отрицательный химический результат — данные
Неверное уравнение может вернуть HTTP 200 с valid:false, неоднозначный баланс — solved:false. Это успешно выполненные вычисления с отрицательным результатом. С другой стороны, сбой поиска нельзя выдавать за отсутствие реакций.
Ограниченные повторы
Сначала исправляйте входные данные. Не запускайте цикл авторизации или запросов с исчерпанной квотой. Преходящий сбой повторяйте в рамках бюджета задачи, соблюдая Retry-After. При потере сетевого ответа используйте тот же ключ идемпотентности записи. Поддержке нужен request_id, а не секрет или полный частный промпт.