POST /v1/agents/{agent_id}/chat и POST /v1/agents/{agent_id}/chat/stream, требуют заголовок Idempotency-Key. Запрос без него — это 422 validation_error.
Выбор ключа
Любое значение длиной 1-255 символов, уникальное для логического запроса. Проще всего — UUID, сгенерированный в момент, когда вы решили отправить сообщение. Ключи идемпотентности привязаны к вашему API-ключу, поэтому о коллизиях с другими API-ключами беспокоиться не нужно.Что возвращает повтор
Повтор с тем жеIdempotency-Key и тем же телом возвращает сохранённый результат: исходный request_id, то же сообщение ассистента и тот же usage. Второй ответ не генерируется, и ничего не списывается повторно.
Записи живут 24 часа. После этого тот же ключ начинает новый запрос.
Сохранённый результат — это то, что рантайм и так сохранил: сообщение ассистента, помеченное идентификатором запроса, и расход LLM, списанный под этим идентификатором. Поэтому повтор никогда не вызывает модель и не трогает баланс, даже если первая попытка оборвалась на полпути.
Конфликты
Стриминг и обрывы соединения
На потоковом эндпоинте правила те же. Если клиент отключился посреди стрима, ответ продолжает генерироваться и сохраняется. Повтор с тем же ключом стримитresponse.created, а сразу за ним response.completed с сохранённым результатом, без воспроизведения дельт. См. Стриминг.