幂等性

使用 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 和相同的 include 查询参数值。状态在 JSON 解析后进行比较:空白无关紧要,但键的顺序有影响——{"a":1,"b":2} 和 {"b":2,"a":1} 是不同的请求。每次尝试都要以相同的方式构建请求体。

选择键

每个逻辑操作使用一个键,并在该操作的多次重试中重复使用它:

  • 你所决策的对象的 ID:lead-8421、ticket:9f2c1d、msg_01HZX3…;
  • 或者在操作开始时一次性生成的 UUID——而不是每次尝试生成一个。

键的作用范围是发送它们的 API 密钥:同一个 Idempotency-Key 分别与 live 密钥和 test 密钥一起使用时,是两个不同的键。

示例

# 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

在第一个调用仍在运行时再次发送相同的调用,会返回带 Retry-After: 1 的 409;一秒后重试即可得到它的响应:

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"
  }
}

在 24 小时内使用 msg-20261005-0042 发送不同的状态,会返回:

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

须知

  • 重放优先返回。 即使决策此后已重新部署或停用,也会返回重放:你得到的正是第一次调用返回的内容,包括其 version。
  • 重放计入速率限制,与任何经过身份验证的请求一样。
  • 并发的重复请求是安全的。 键在决策运行之前就已预留,因此同时发送的两个使用相同键的请求永远不会都运行——也不会都计费或都投递:第二个会得到带 Retry-After: 1 的 409,其重试会得到已存储的响应。SDK 会自行等待并重试。
  • 错误会释放键。 键在身份验证、速率限制和请求体检查之后立即被检查:之后的任何失败——未知或已停用的决策、配额、无效的状态、引擎错误——都会释放它,下一次尝试会重新开始。
  • 按子工作区区分。 使用 Dcision-Workspace 请求头时,目标子工作区是请求的一部分:同一个键用于两位客户会产生 409 冲突,永远不会返回另一位客户已存储的回答。
  • 已存储的响应包含回答。 无论决策的 storeOutput 设置如何,它们都会保存 24 小时;状态本身不会为幂等性而存储。
  • SDK 和 CLI 会替你处理。 SDK 会在每次 decide 调用时发送一个 Idempotency-Key,并在重试时复用它;dcision decide 在你未传入键时会生成一个,并在网络错误时重试一次——参见 CLI。

JavaScript 和 Python 的完整客户端示例请参见幂等重试。

本页内容