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

Безопасные повторы с заголовком Idempotency-Key — ключи резервируются до запуска, успешные вызовы повторяются из хранилища 24 часа, заголовок Idempotent-Replayed и IDEMPOTENCY_CONFLICT.

Тайм-аут или оборванное соединение могут потерять ответ решения, которое уже выполнилось. Слепой повтор выполнил бы — и тарифицировал — его дважды. Отправьте Idempotency-Key, и повтор получит сохранённый ответ.

Idempotency-Key: lead-8421

Ключ — это от 1 до 128 символов из A–Z a–z 0–9 . _ : -. Всё остальное завершается ошибкой 400 INVALID_REQUEST.

Поведение

СитуацияЧто происходит
Новый ключКлюч резервируется за этим запросом до запуска решения. Если решение выполнилось успешно (200), его ответ хранится 24 часа.
Тот же ключ, тот же запрос, в течение 24 часовВозвращается сохранённый ответ с заголовком Idempotent-Replayed: true — тот же execution_id, те же ответы, те же записи назначений. Решение не выполняется снова, ничего не тарифицируется, ничего не доставляется и выполнение не записывается.
Тот же ключ, тот же запрос, пока первый ещё выполняется409 IDEMPOTENCY_CONFLICT с Retry-After: 1 — "A request with this Idempotency-Key is still running. Retry in a moment to get its response." Повторите через секунду: когда первый запрос завершится, вы получите его сохранённый ответ. Решение никогда не выполняется дважды.
Тот же ключ, другой запрос, в течение 24 часов409 IDEMPOTENCY_CONFLICT без Retry-After — "This Idempotency-Key was already used with a different request body." — даже пока первый запрос выполняется.
Тот же ключ через 24 часаСчитается новым ключом.
Первый запрос завершился ошибкойРезервирование снимается, поэтому повтор с тем же ключом снова выполняет решение.
Первый запрос получил fallback при ошибке движка (action_reason.type = "engine_error")Резервирование тоже снимается: повтор с тем же ключом снова обращается к движку — и его назначения срабатывают снова, с новыми ID доставок.
Первый запрос так и не завершился — сервер остановился посреди выполненияРезервирование истекает через 2 минуты; после этого ключ можно использовать снова.

«Тот же запрос» означает тот же slug, тот же state и то же значение query-параметра include. State сравнивается после разбора JSON: пробелы не имеют значения, но порядок ключей имеет — {"a":1,"b":2} и {"b":2,"a":1} — разные запросы. Формируйте тело одинаково при каждой попытке.

Выбор ключей

Используйте один ключ на логическую операцию и переиспользуйте его во всех повторах этой операции:

  • ID того, о чём вы принимаете решение: lead-8421, ticket:9f2c1d, msg_01HZX3…;
  • или UUID, сгенерированный один раз в начале операции, — а не на каждую попытку.

Ключи ограничены API-ключом, который их отправил: один и тот же Idempotency-Key, использованный с рабочим и тестовым ключом, — это два разных ключа.

Пример

# First call: runs the decision.
curl -i -X POST https://api.dcision.io/v1/decisions/spam-detection \
  -H "Authorization: Bearer $DCISION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-20261005-0042" \
  -d '{ "state": "Congratulations! You won a $1000 gift card, click here to claim now." }'

# Same call again: replayed.
# HTTP/1.1 200 OK
# Idempotent-Replayed: true

Повторная отправка того же вызова, пока первый ещё выполняется, возвращает 409 с Retry-After: 1; повторите через секунду, чтобы получить его ответ:

409 Conflict — запрос ещё выполняется
{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "A request with this Idempotency-Key is still running. Retry in a moment to get its response.",
    "request_id": "req_Hn5Wq2Lk8Tz1Vb4Xc7Pm"
  }
}

Отправка другого state с msg-20261005-0042 в течение 24 часов возвращает:

409 Conflict
{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "This Idempotency-Key was already used with a different request body.",
    "request_id": "req_Fw2Lk9Tq7Mz1Vb6Xc3Pn"
  }
}

Полезно знать

  • Повторы обслуживаются в первую очередь. Повтор возвращается, даже если решение с тех пор было опубликовано заново или отключено: вы получаете ровно то, что вернул первый вызов, включая его version.
  • Повторы учитываются в лимите запросов, как любой аутентифицированный запрос.
  • Одновременные дубликаты безопасны. Ключ резервируется до запуска решения, поэтому два запроса, отправленные одновременно с одним ключом, никогда не выполняются оба — и не тарифицируются, и не доставляются дважды: второй получает 409 с Retry-After: 1, а его повтор получает сохранённый ответ. SDK ждут и повторяют сами.
  • Ошибки освобождают ключ. Ключ проверяется сразу после аутентификации, лимита запросов и тела: любая последующая ошибка — неизвестное или отключённое решение, квота, некорректный state, ошибка движка — освобождает его, и следующая попытка начинается заново.
  • Отдельно для каждого подпространства. С заголовком Dcision-Workspace целевое подпространство — часть запроса: один и тот же ключ, использованный для двух клиентов, даёт конфликт 409, а не сохранённый ответ другого клиента.
  • Сохранённые ответы содержат ответы решения. Они хранятся 24 часа независимо от настройки storeOutput решения; сам state для идемпотентности не сохраняется.
  • SDK и CLI делают это за вас. SDK отправляют Idempotency-Key с каждым вызовом decide и переиспользуют его при повторах; dcision decide генерирует ключ, если вы его не передали, и один раз повторяет запрос при сетевых ошибках — см. CLI.

Полный клиент на JavaScript и Python см. в разделе Идемпотентные повторы.

На этой странице