幂等重试

一个可用于生产的 Dcision 客户端——幂等键、超时、哪些错误需要重试、带 Retry-After 的指数退避——提供 JavaScript 和 Python 版本。

网络会出故障。请求可能在决策已经运行之后在你这一侧超时,提供商可能短暂过载,突发流量可能触及你的速率限制。一个好的客户端会重试正确的错误,等待正确的时长,并且永远不会让同一个决策运行——或付费——两次。

官方 SDK 会替你完成这一切。本指南介绍这些规则,并给出一个在你直接调用 API 时使用的完整客户端。

规则

  1. 每个操作一个 Idempotency-Key,该操作的每次重试都复用它——线索、工单或消息的 ID 就很合适。这样,对已成功调用的重试会在 24 小时内被重放,而不是再次运行。
  2. 每次都以相同的方式构建请求体。重放检查会把状态作为解析后的 JSON 进行比较,包括键的顺序;使用相同的键发送不同的请求体会得到 409 IDEMPOTENCY_CONFLICT。
  3. 在你这一侧设置超时,比 Dcision 稍晚一点。Dcision 已经在决策的 timeoutMs(默认 5 秒)内重试引擎——最多 2 次重试;你这一侧设置 10 秒可以为此留出余地。两者要一起调高。
  4. 只重试以后可能成功的情况:网络错误、429、500、503、504、带有 Retry-After 的 409 IDEMPOTENCY_CONFLICT——使用该键的第一个请求仍在运行——以及 502 ENGINE_ERROR 一次。其他一切都需要修复。
  5. 在 429 和 409 上遵循 Retry-After;否则使用带抖动的指数退避。
  6. 限制尝试次数,然后走你的错误路径——通常与 escalate 相同。

JavaScript

dcision.js
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);
usage
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

dcision.py
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)
usage
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——重试会再次运行,并再次计费。
  • 不要让你自己的重试相互竞争。同时发送的两个使用相同键的请求永远不会都运行——第二个会得到带 Retry-After: 1 的 409——但这会浪费一次往返和一个速率限制名额。请在失败或超时之后再重试。
  • 不要原样重试 4xx 错误(429 除外):INVALID_STATE、DECISION_DISABLED、CREDITS_EXHAUSTED 或 QUOTA_EXCEEDED 不会自行修复。
  • 不要把不带 Retry-After 的 IDEMPOTENCY_CONFLICT 当作暂时性错误。它意味着两个不同的请求共用了一个键——这是键的构建方式有缺陷。带有 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}` });

CLI 的 dcision decide 遵循相同的规则:当你没有传入 Idempotency-Key 时它会生成一个,并在网络错误时重试一次。

本页内容