BroadRouter
Начать

Ключ идемпотентности (idempotency key)

Обновлено

Ключ идемпотентности — это уникальное значение, обычно случайный ID вроде UUID, которое клиент прикладывает к запросу, меняющему состояние, например к платежу или покупке. Если тот же запрос приходит снова с тем же ключом, сервер возвращает исходный результат, а не выполняет действие второй раз.

Также называют: ключ идемпотентности, идемпотентный запрос, идемпотентность API, идемпотентный повтор, заголовок Idempotency-Key, idempotency key, Idempotency-Key header, idempotency token, idempotent request, idempotent retry

Сеть подводит в самый неудачный момент: когда сервер уже выполнил действие, а ответ до вас не дошёл. Ключ идемпотентности делает повтор безопасным.

Как это работает

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

Рабочая группа IETF HTTPAPI стандартизирует это как заголовок запроса Idempotency-Key (черновик 08, октябрь 2026 года, пока не RFC). Ключ описан в нём как “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (перевод: «уникальное значение, сгенерированное клиентом, по которому ресурс распознаёт последующие повторы того же запроса»), а в качестве ключа рекомендуется UUID или похожий случайный ID. Ошибочные случаи по черновику:

Ситуация Статус
Ключ отсутствует, хотя обязателен 400 Bad Request
Исходный запрос ещё выполняется 409 Conflict
Ключ повторно использован с другим телом 422 Unprocessable Content

AWS Builders’ Library говорит то же самое со стороны клиента: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (перевод: «API с побочными эффектами небезопасно вызывать повторно, если они не обеспечивают идемпотентность».)

Почему это важно

Повторы с экспоненциальной задержкой — стандартная практика, и многие SDK повторяют запросы автоматически. Без идемпотентности повтор после тайм-аута может создать два заказа или два списания. С ключом повтор безопасен, что бы ни сделала первая попытка. Поэтому это базовый инструмент для агентов и скриптов, которые покупают, бронируют или создают что-то без присмотра человека.

В BroadNet Inference

BroadNet применяет этот подход при покупке почасовых ключей. POST /portal/keys/hourly принимает request_id в JSON-теле, а документация утверждает: “Idempotency is required for money safety” (перевод: «Идемпотентность обязательна для финансовой безопасности»):

curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
  -H "Authorization: Bearer <portal-credential>" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"order-20260920-001","label":"kiosk-1"}'

Повторное использование request_id не создаёт ещё один ключ и не списывает за него деньги. После тайм-аута, обрыва соединения, ответа 409 mint_in_progress или 5xx повторяйте запрос с тем же request_id. Повторный ответ вернёт already_issued: true и алиас ключа; сам ключ в открытом виде есть только в первом успешном ответе. В документации сказано: “Never generate a replacement id until the original result is known.” (перевод: «Никогда не генерируйте новый id, пока не известен результат исходного запроса».)

BroadNet не описывает ключ идемпотентности для /v1/chat/completions и транскрибации. Что там стоит повторять, смотрите в руководстве коды ошибок и повторы, а почему слепые повторы могут усугубить 429 — в статье о лимитах запросов.

Вопросы и ответы

Когда нужно генерировать новый ключ идемпотентности?

Только для нового задуманного действия. Для всех повторов одного действия используйте один и тот же ключ и не создавайте новый, пока не узнаете, чем закончилась первая попытка.

Нужен ли ключ идемпотентности для запросов chat completions к LLM?

Генерация текста не оставляет долговременных побочных эффектов, поэтому повторный чат-запрос обычно просто снова тратит токены. Ключ важен для вызовов, которые списывают деньги или создают ресурсы. BroadNet описывает его только для покупки почасовых ключей, а не для chat completions.

Что будет, если повторно использовать ключ с другим телом запроса?

По черновику IETF сервер должен отклонить такой запрос с кодом 422 Unprocessable Content, потому что ключ уже привязан к другому запросу.

Открыть в MarkdownСпросить ChatGPTСпросить ClaudeСпросить Perplexity