Проще говоря, idempotency key защищает от дублей. Если сеть оборвалась, пользователь нажал кнопку дважды, workflow сделал retry или AI-агент повторил tool call, система не должна создать два заказа, два платежа, две заявки, два письма или две записи в CRM.
Идемпотентность особенно важна для write-действий: оплат, счетов, заявок, отправки email, создания сделок, обновления статусов, запуска задач и любых операций с побочным эффектом. Для обычного чтения данных ключ обычно не нужен, потому что повторный GET-запрос не меняет состояние системы.
В AI-агентах idempotency key полезен как защитный слой вокруг инструментов. Агент может ошибиться, повторить действие после таймаута или запустить retry. Если каждый опасный tool call получает стабильный ключ операции, backend сможет понять: это новая команда или повтор уже обработанной.
Примеры
- Платежный API получает два одинаковых запроса с одним idempotency key и создает только один платеж.
- AI-агент повторяет tool call после таймаута, но CRM не создает дубль сделки.
- Workflow отправляет заявку в service desk с ключом операции, чтобы retry не создал второй тикет.
- Система сохраняет результат первого запроса и возвращает его при повторе с тем же ключом.
- Для отправки письма ключ строят из ID задачи и типа уведомления, чтобы письмо не ушло дважды.
Где используется
- Защита платежей, заказов и счетов от дублей
- Безопасные retry в API и webhook-интеграциях
- Создание заявок, тикетов, сделок и задач через AI-агента
- Отправка email, сообщений и уведомлений без повторов
- Контроль write-действий в tool calling
- Надежная работа очередей, background jobs и workflow automation
- Audit log и расследование повторных запросов
Связанные термины
API credentials
Approval workflow
Audit log
Payment Approval
Payment Matching
Rate Limit
Retry
Run ID
Частые вопросы
Чем idempotency key отличается от request id?
Request id часто нужен для трассировки конкретного HTTP-запроса. Idempotency key описывает логическую операцию и должен повторяться при retry, чтобы сервер не выполнил действие заново.
Где хранить idempotency key?
Обычно на сервере: в базе, кеше или отдельной таблице операций вместе со статусом, результатом, временем жизни и параметрами запроса. Важно уметь вернуть тот же результат при повторе.
Нужен ли idempotency key для всех запросов?
Нет. Он особенно нужен для операций с побочным эффектом: создать, оплатить, отправить, изменить, запустить. Для чтения данных обычно достаточно обычного request id и логов.
Как AI-агенту использовать idempotency key?
Для каждого write-действия backend должен генерировать стабильный ключ операции: например, из ID задачи, пользователя, типа действия и целевого объекта. Тогда повторный tool call не создаст дубль.
