Идемпотентность и повторы

Безопасность повторов уже, чем обычно предполагают клиенты. Эта страница перечисляет ровно то, что платформа гарантирует сегодня; всё, чего здесь нет, не идемпотентно.

Заголовок Idempotency-Key

Факт	Значение
Где учитывается	Каждая запись под /api/v1/ (POST/PATCH/PUT/DELETE) — кэш повторов на HTTP-уровне; POST /api/v1/tasks и POST /api/v1/tickets дополнительно сохраняют ключ на созданной записи
Формат	Любой UUID, один на логический запрос
Окно	24 часа: повтор с тем же ключом возвращает исходный ответ, а не создаёт второй объект
Тот же ключ, другое тело	422 с code: "idempotency_conflict" и detail: "Idempotency-Key conflict: same key used with different request body" — ключ привязан к первому телу
Что воспроизводится	Ответы 2xx и 4xx; 5xx не кэшируется, поэтому упавший вызов можно повторить с тем же ключом. Воспроизведённый ответ несёт idempotent-replayed: true
В контракте	Объявлен необязательным заголовком на каждой пишущей операции в openapi.json

curl -sS -X POST https://entherium.duckdns.org:8443/api/v1/tasks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1a6c62-0b5e-4d0f-9d1e-1f6a3b2c4d5e" \
  -d '{"title": "Re-check the source feeds of contract 42"}'

Естественно идемпотентные операции

Операция	Почему повтор безопасен
Любой GET	У чтений нет побочных эффектов
Отчёты о дефектах / предложения (POST /api/v1/tickets, MCP entherium_report_defect, entherium_propose_improvement)	Intake дедуплицирует по отпечатку содержимого: повторный отчёт сворачивается в существующий тикет, а не заводится дважды — поверх заголовка
MCP entherium_target_task_spec, entherium_reassign_task	Повторная установка той же цели оставляет то же состояние (idempotentHint: true)
PATCH, выставляющий полю уже имеющееся значение	No-op по построению; исключение — переходы статусов ниже

Не идемпотентны — сначала прочитайте состояние

Операция	Что делает повтор
entherium_update_task_status / resolve · dismiss · reopen тикета	Второй вызов попадает в состояние, которое переход уже не допускает → 409 illegal transition. Перечитайте перед решением
entherium_log_task_note	Добавляет вторую заметку
Запуски прогонов (POST /api/v1/runs/…)	Запускают ещё один прогон; проверьте список прогонов, прежде чем повторять запуск, ответ на который потерян
Записи агента в сущности	Применяются каждый раз; потерянный ответ не значит потерянную запись — перечитайте перед повтором

Как повторять, по классам ошибок

Получили	Повторять?	Как
Сетевой таймаут / обрыв	Да — для чтений и для двух intake-эндпоинтов с тем же Idempotency-Key; для остальных записей сначала перечитайте	Экспоненциальная пауза от 1 с, не более 5 попыток
429	Да	Подождите Retry-After секунд и повторите тот же запрос
500	Один раз	Короткая пауза; если повторяется — заведите дефект с request_id
502 / 503 / 504	Да, медленно	Платформа лежит, остановлена или не готова — опрашивайте статус, а не долбите запросами
Любой другой 4xx	Нет	Запрос неверен; detail и doc_url говорят, что исправить (Ошибки)

MCP: что обещают подсказки

Каждый инструмент объявляет idempotentHint и readOnlyHint (справочник). Инструменты с readOnlyHint: true можно повторять свободно. Пишущий инструмент с idempotentHint: true можно повторить с теми же аргументами; с idempotentHint: false — нельзя без предварительного чтения объекта. Подсказки выводятся из того же кода, который выполняет инструменты, поэтому не могут устареть относительно сервера, к которому вы подключены.