Skip to main content
此页面由英文翻译而成。英文版为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。

​
幂等性与重试

配送标签涉及实际的成本和物流影响。重复标签会导致运营混乱、配送费用浪费以及库存追踪错误。Flex Forward API 内建幂等性来防止此问题。

​
幂等性的工作方式

POST /labels 端点使用 idempotencyKey 字段来确保每个标签创建请求只会被处理一次。 第一次请求 — API 创建标签并返回 HTTP 201：
201 Created
重放的请求 — 相同的 idempotencyKey 会返回原始结果（HTTP 200），而不会创建新标签：
200 OK（幂等重放）
幂等性密钥的范围限于您的 API 账户。不同账户可以使用相同的密钥而不会冲突。

​
选择幂等性密钥

密钥应该唯一标识预期的标签创建。良好的模式：
重试相同的逻辑请求时，绝不要生成新的 idempotencyKey。请重复使用原始密钥，以便 API 能检测重复。
400 验证错误后，由于未创建标签，可以重复使用相同的 idempotencyKey。修正请求后使用相同密钥重试。

​
重试策略

对于暂时性失败（HTTP 500、502 或网络超时），请使用指数退避重试：
1

设置请求超时

为 HTTP 请求设置合理的超时时间（例如 30 秒）。
2

失败时等待再重试

使用指数退避：1 秒、2 秒、4 秒、8 秒。
3

重复使用相同的幂等性密钥

始终使用与原始请求相同的 idempotencyKey 重试。即使原始请求已成功但响应丢失，也能确保不会创建重复标签。
4

限制重试次数

在 3–5 次重试后停止。如果请求仍然失败，记录错误并升级调查。

​
各端点的幂等性

​
失败场景

标签可能已创建也可能未创建。使用相同的 idempotencyKey 重试。如果标签已创建，API 会返回 HTTP 200 和原始结果。如果未创建，API 会创建标签并返回 HTTP 201。
暂时性服务器错误。使用相同的 idempotencyKey 并以退避策略重试。
物流商服务返回错误。标签以 status: failed 保存。重试前请检查错误消息 — 部分物流商错误需要修改请求（如无效地址）。对于暂时性的物流商问题，使用相同的 idempotencyKey 重试。
请求无效。未修正请求前请勿重试。由于未创建标签，修正请求体后可以重复使用相同的 idempotencyKey。