Идемпотентность

Безопасная повторная отправка запросов через idempotency-key.

Мутирующие запросы принимают заголовок idempotency-key. Если запрос с тем же ключом уже выполнялся, сервер вернёт сохранённый ответ, не выполняя операцию повторно — безопасно ретраить сетевые ошибки и таймауты.

POST /api/v1/tasks HTTP/1.1
Authorization: Bearer <token>
idempotency-key: 4f3c8b27-9a1e-4c05-8f60-2d7c1b9e5a11

Правила:

Формат ключа: 8–255 символов из набора A-Za-z0-9_.:+/=-. Практичный выбор — UUID v4 на каждую логическую операцию.
Ответ кэшируется на 24 часа. Повтор внутри этого окна возвращает исходный ответ; после — выполняется как новый запрос.
Ключ привязан к телу запроса: повтор с тем же ключом, но другим телом отклоняется как конфликт.
Если первый запрос ещё выполняется, повтор получит ответ о выполняющейся операции — подождите и повторите.