Идемпотентность
Безопасные повторы с заголовком 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; повторите через секунду, чтобы получить его ответ:
{
"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 часов возвращает:
{
"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 см. в разделе Идемпотентные повторы.
Rate limits
Лимиты запросов на рабочее пространство для каждого тарифа, отдельные окна для решений и чтения, заголовки X-RateLimit в каждом вызове, Retry-After при 429 и как снижать нагрузку.
Лимиты
Все ограничения размеров и количества в одном месте — тело запроса, state и бюджет токенов, схема решения, назначения и доставки, идентификаторы, рабочее пространство, команда и вход.