幂等性
使用 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;一秒后重试即可得到它的响应:
{
"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 发送不同的状态,会返回:
{
"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 的完整客户端示例请参见幂等重试。