---
title: Идемпотентность и повторы
description: Что на самом деле идемпотентно на платформе — заголовок Idempotency-Key на двух intake-эндпоинтах, его окно 24 часа и правило конфликта, дедупликация отчётов, какие MCP-инструменты безопасно повторять — и как повторять запрос по классам ошибок.
locale: ru
version: 0.2.0
canonical: https://enterium-developer-docs.pages.dev/developers/ru/reference/idempotency/
---

> Documentation index: https://enterium-developer-docs.pages.dev/developers/llms.txt — every page of this portal has a Markdown twin at <route>.md; the frozen API contract is at https://enterium-developer-docs.pages.dev/developers/api/openapi.json.

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

## Заголовок `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` |

```sh
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` | Да, медленно | Платформа лежит, остановлена или не готова — опрашивайте [статус](../status/), а не долбите запросами |
| Любой другой `4xx` | Нет | Запрос неверен; `detail` и `doc_url` говорят, что исправить ([Ошибки](../errors/)) |

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

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