Идемпотентные повторы
Готовый к продакшену клиент Dcision — ключи идемпотентности, тайм-ауты, какие ошибки повторять, экспоненциальная задержка с Retry-After — на JavaScript и Python.
Сети дают сбои. На вашей стороне запрос может истечь по тайм-ауту уже после того, как решение выполнилось, провайдер может быть ненадолго перегружен, всплеск может упереться в ваш rate limit. Хороший клиент повторяет нужные ошибки, ждёт нужное время и никогда не запускает — и не оплачивает — одно и то же решение дважды.
Официальные SDK делают всё это за вас. Это руководство показывает правила и полный клиент на случай, когда вы вызываете API напрямую.
Правила
- Один
Idempotency-Keyна операцию, повторно используемый каждым её повтором, — хорошо подходит ID лида, тикета или сообщения. Тогда повтор успешного вызова воспроизводится в течение 24 часов, а не выполняется заново. - Каждый раз собирайте тело одинаково. Проверка повтора сравнивает state как разобранный JSON, включая порядок ключей; другое тело с тем же ключом — это
409 IDEMPOTENCY_CONFLICT. - Ставьте тайм-аут на своей стороне чуть позже, чем Dcision. Dcision уже повторяет запрос к движку — до 2 повторов — в пределах
timeoutMsрешения (по умолчанию 5 секунд); 10 секунд на вашей стороне оставляют для этого место. Повышайте оба значения вместе. - Повторяйте только то, что может получиться позже: сетевые ошибки,
429,500,503,504,409 IDEMPOTENCY_CONFLICTсRetry-After— первый запрос с этим ключом ещё выполняется — и502 ENGINE_ERRORодин раз. Всё остальное исправляйте. - Соблюдайте
Retry-Afterпри429и409; в остальных случаях увеличивайте задержку экспоненциально со случайным разбросом. - Ограничьте число попыток, а затем идите по своему пути обработки ошибок — обычно тому же, что и для
escalate.
JavaScript
import { randomUUID } from "node:crypto";
const API = "https://api.dcision.io/v1/decisions";
const RETRYABLE_STATUS = new Set([429, 500, 503, 504]);
export class DcisionError extends Error {
constructor(status, error) {
super(`${error.code}: ${error.message}`);
Object.assign(this, { status, code: error.code, requestId: error.request_id, details: error.details });
}
}
/** Runs a decision with retries. Pass a stable idempotencyKey (e.g. the record's ID) per operation. */
export async function decide(slug, state, { idempotencyKey = randomUUID(), attempts = 4, timeoutMs = 10_000 } = {}) {
for (let attempt = 1; ; attempt++) {
let response;
try {
response = await fetch(`${API}/${slug}`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.DCISION_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify({ state }),
signal: AbortSignal.timeout(timeoutMs),
});
} catch (networkError) {
// The decision may or may not have run: the same Idempotency-Key makes the retry safe.
if (attempt >= attempts) throw networkError;
await sleep(backoff(attempt));
continue;
}
const body = await readJson(response);
if (response.ok) return body;
const error = body?.error ?? { code: "INTERNAL_ERROR", message: `HTTP ${response.status}` };
const retryable =
RETRYABLE_STATUS.has(response.status) ||
(error.code === "ENGINE_ERROR" && attempt === 1) ||
// Same key still running: wait for Retry-After, then get its stored response.
(error.code === "IDEMPOTENCY_CONFLICT" && response.headers.has("Retry-After"));
if (!retryable || attempt >= attempts) throw new DcisionError(response.status, error);
const retryAfter = Number(response.headers.get("Retry-After"));
await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
}
}
async function readJson(response) {
try {
return await response.json();
} catch {
return null; // e.g. an HTML error page from a proxy
}
}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const backoff = (attempt) => Math.min(8_000, 250 * 2 ** attempt) * (0.5 + Math.random() / 2);import { DcisionError, decide } from "./dcision.js";
try {
const decision = await decide("lead-qualification", { message: lead.message, company_size: lead.size }, {
idempotencyKey: `lead-${lead.id}`,
});
await act(decision);
} catch (error) {
if (error instanceof DcisionError && error.code === "INVALID_STATE") return reportBadInput(lead, error.message);
await escalate(lead, error); // retries exhausted or a non-retryable error
}Python
import os
import random
import time
import uuid
import requests
API = "https://api.dcision.io/v1/decisions"
RETRYABLE_STATUS = {429, 500, 503, 504}
class DcisionError(Exception):
def __init__(self, status, error):
super().__init__(f"{error['code']}: {error['message']}")
self.status = status
self.code = error["code"]
self.request_id = error.get("request_id")
self.details = error.get("details")
def decide(slug, state, idempotency_key=None, attempts=4, timeout=10):
"""Runs a decision with retries. Pass a stable idempotency_key (e.g. the record's ID) per operation."""
key = idempotency_key or str(uuid.uuid4())
for attempt in range(1, attempts + 1):
try:
response = requests.post(
f"{API}/{slug}",
headers={
"Authorization": f"Bearer {os.environ['DCISION_API_KEY']}",
"Idempotency-Key": key,
},
json={"state": state},
timeout=timeout,
)
except requests.RequestException:
# The decision may or may not have run: the same Idempotency-Key makes the retry safe.
if attempt == attempts:
raise
time.sleep(_backoff(attempt))
continue
try:
body = response.json()
except ValueError:
body = None # e.g. an HTML error page from a proxy
if response.ok:
return body
error = (body or {}).get("error") or {"code": "INTERNAL_ERROR", "message": f"HTTP {response.status_code}"}
retryable = (
response.status_code in RETRYABLE_STATUS
or (error["code"] == "ENGINE_ERROR" and attempt == 1)
# Same key still running: wait for Retry-After, then get its stored response.
or (error["code"] == "IDEMPOTENCY_CONFLICT" and "Retry-After" in response.headers)
)
if not retryable or attempt == attempts:
raise DcisionError(response.status_code, error)
retry_after = response.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else _backoff(attempt))
def _backoff(attempt):
return min(8.0, 0.25 * 2**attempt) * (0.5 + random.random() / 2)from dcision import DcisionError, decide
try:
decision = decide(
"support-routing",
{"message": ticket["message"], "plan": ticket["plan"]},
idempotency_key=f"ticket-{ticket['id']}",
)
act(decision)
except DcisionError as error:
escalate(ticket, error)Чего не делать
- Не генерируйте новый
Idempotency-Keyдля каждой попытки — повторы выполнятся и будут оплачены заново. - Не устраивайте гонку собственных повторов. Два запроса, отправленные одновременно с одним ключом, никогда не выполнятся оба — второй получит
409сRetry-After: 1, — но это стоит лишнего сетевого обмена и места в rate limit. Повторяйте после ошибки или тайм-аута. - Не повторяйте ошибки
4xxбез изменений (кроме429):INVALID_STATE,DECISION_DISABLED,CREDITS_EXHAUSTEDилиQUOTA_EXCEEDEDсами не исправятся. - Не считайте
IDEMPOTENCY_CONFLICTбезRetry-Afterвременной ошибкой. Это значит, что у двух разных запросов один ключ, — ошибка в том, как строятся ключи. СRetry-Afterэто лишь значит, что первый запрос ещё выполняется.
С fallback при ошибке движка
Решение, у которого onEngineError равно fallback, отвечает 200 даже при сбое движка, с action_reason.type = "engine_error". Клиент выше возвращает такой ответ как любой другой. Если вы предпочитаете настоящие ответы, когда их недорого подождать, повторите вызов позже с тем же ключом: ответы fallback не тарифицируются и не сохраняются для идемпотентности, поэтому повтор снова доходит до движка — и снова запускает назначения решения, с новыми ID доставок.
const decision = await decide("lead-qualification", state, { idempotencyKey: `lead-${lead.id}` });
if (decision.action_reason.type === "engine_error") queue.retryLater({ lead, idempotencyKey: `lead-${lead.id}` });dcision decide из CLI следует тем же правилам: он генерирует Idempotency-Key, если вы его не передали, и один раз повторяет запрос при сетевых ошибках.
Обзор и калибровка
Как читать вкладку «Обзор» решения — запуски, доля успешных, задержка, стоимость, действия, причины и статистика по вопросам — и действовать по каждой подсказке калибровки с её порогами.
Тарифы, квоты и оплата
Genesis, Developer, Growth и Enterprise — включённые решения, предоплаченные кредиты сверх них, rate limits, лимиты решений и журналов — что тарифицируется и как работают кредиты, смена тарифа, отмена и счета.