Ошибка Claude 400: что делать, если после tool_use нет tool_result

Сообщение Claude об отсутствии соответствующего tool_result для tool_use обычно указывает на нарушенную последовательность инструментов, а не на неудачную формулировку промпта. В нативном Messages API ассистент вызывает клиентский инструмент, а следующее сообщение пользователя возвращает результат с тем же ID. Проверьте эту связь перед повторной отправкой.

Руководство касается именно этого семейства ошибок в интеграциях и клиентах вроде OpenCode. Не каждый HTTP 400 в OpenCode имеет такую причину. Правила взяты из документации обработки вызовов Claude, проверенной 14 сентября 2026 года. Примеры созданы для объяснения структуры, а не взяты из логов реального API-теста.

Сначала найдите ID без пары

Прочитайте полное сообщение ошибки и найдите указанный ID в предыдущем сообщении ассистента. Затем проверьте следующее пользовательское сообщение: tool_result.tool_use_id должен точно совпадать с ним. Имя инструмента не заменяет идентификатор вызова.

В нативном Claude результат инструмента — блок content пользовательского сообщения. В этой форме нет нативного role: "tool". Если адаптер поддерживает другой формат, он должен преобразовать роли и поля, а не переслать их без изменений.

Минимальный корректный фрагмент

JSON показывает лишь необходимые сообщения. Полный запрос также требует модель, определение инструмента, токеновый лимит и остальную историю. Демонстрационный результат вымышлен и не заменяет выполнение реального инструмента.

[
  {
    "role": "assistant",
    "content": [
      {"type": "tool_use", "id": "toolu_demo", "name": "lookup", "input": {"key": "demo"}}
    ]
  },
  {
    "role": "user",
    "content": [
      {"type": "tool_result", "tool_use_id": "toolu_demo", "content": "demo result"}
    ]
  }
]

Не восстанавливайте ответ ассистента из текста окна чата. Сохраняйте полное структурированное содержимое API. Могут потребоваться и другие блоки, включая данные рассуждений, если их требует модель и сценарий. Проверка подписей — отдельная проблема; см. руководство по thinking-подписям Claude.

Для параллельных вызовов верните все результаты

Если одно сообщение ассистента запросило два клиентских инструмента, соберите оба результата в непосредственно следующем пользовательском сообщении. Нельзя вернуть один, вставить новый ход ассистента и лишь потом отправить второй к прежнему вызову. Разрешённый поясняющий пользовательский текст размещайте после блоков результатов.

Официальная диагностика также описывает смешанные сценарии с серверными инструментами. Если в том же раунде серверный инструмент ещё не завершён, сообщение пользователя должно содержать только клиентские результаты, а массив tools нужно сохранить. Минимальный клиентский пример не покрывает все серверные сценарии.

Передавайте реальные ошибки, не выдумывая успех

Неудачный поиск или команда могут иметь правильно сопоставленный результат. Если это предусмотрено клиентским протоколом, верните исходный ID, is_error: true и точное описание ошибки. Валидность связи сообщений и успех операции — разные проверки.

При прерывании клиента сначала установите, выполнился ли инструмент. Тайм-аут интерфейса не доказывает, что запись файла, публикация или внешний запрос не состоялись. Проверьте состояние перед повтором операций с побочными эффектами. Не придумывайте успешный ответ для валидатора и не выполняйте значимое действие автоматически дважды.

В разработке воспроизводите последовательность безвредным чтением во временной сессии. Такой пример выявляет ошибку без повторной записи или транзакции. Сохраните версию клиента и сообщения до и после прерывания.

Восстанавливайте историю осторожно

Перед исправлением сохраните локальную копию истории. Если исходный результат доступен, восстановите правильную пару поддерживаемым механизмом клиента. Если безопасно исправить историю нельзя, откройте новую сессию с кратким перечнем подтверждённой работы и оставшихся действий, сохранив старую для справки.

Произвольное удаление блоков меняет представление модели о выполненной работе. Поэтому удалять все файлы диалога по умолчанию не следует. В issue приложите небольшой обезличенный пример с ролями, типами content и ID. Удалите API-ключи, приватные аргументы и результаты.

Проверьте release notes обновления клиента, но эта статья не называет версию, исправляющую каждый случай. Исторический issue подтверждает сбой конкретной конфигурации, а не наличие того же бага в последней версии.

Почему одного повтора недостаточно

API проверяет структуру истории до продолжения хода модели. Повтор той же последовательности без пары сохраняет структурную ошибку. Это вывод из правил протокола, а не измерение реализации повтора во всех клиентах.

HTTP 429 или перегрузка требуют другой диагностики. До применения этого руководства проверьте статус и тело ошибки. Инструкция model-not-found (на английском) касается других ошибок доступа и другого протокола; не смешивайте их со связями сообщений Claude.

Частые вопросы

Ошибка инструмента может удовлетворять требованию пары?

Да. Честное сообщение об ошибке может ссылаться на исходный tool-use ID. Успешное исполнение не требуется, чтобы корректно описать сбой в следующем сообщении.

Нужен role tool в нативном API Claude?

Нет. Результаты клиентских инструментов находятся в content пользовательского сообщения. Совместимый с OpenAI адаптер может иметь другую форму; следуйте протоколу принимающего endpoint.

Новая сессия полностью решает проблему?

Она может отделить повреждённую историю, но не исправляет адаптер, продолжающий удалять результаты. Проверьте сериализацию и клиентский путь, создавший ошибочную последовательность.