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

幂等性与重试

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

幂等性的工作方式

POST /labels 端点使用 idempotencyKey 字段，让标签创建可以安全地重试。使用特定密钥的第一次请求会尝试创建标签。之后使用相同密钥和相同请求体的请求会以 HTTP 200 返回已保存的结果。使用不同请求体重复密钥会返回 HTTP 409，代码为 IDEMPOTENCY_CONFLICT。 第一次请求 — API 创建标签并返回 HTTP 201：

curl -X POST https://api.flexforwardship.com/labels \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "N-2026-05-27-TEST-03",
    "courier": "yunexpress",
    ...
  }'

201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

重放的请求 — 相同的 idempotencyKey 和请求体会返回原始结果（HTTP 200），而不会创建新标签：

200 OK（幂等重放）

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": null,
  "error": null
}

幂等性密钥的范围限于您的 API 账户。不同账户可以使用相同的密钥而不会冲突。密钥不会过期。重试时请保持请求体不变。如果收到 IDEMPOTENCY_CONFLICT，请使用原请求体获取已保存结果，或为修改后的请求使用新密钥。即使只更改 customerOrderNumber 而保留相同密钥，仍会导致冲突。旧标签或由其他工作流创建的标签可能没有保存请求指纹。对于这些记录，即使请求体不同，重复使用密钥仍会返回原始结果。请勿依赖冲突检测来验证旧标签的详细信息。

绝不要同时发送两个使用相同 idempotencyKey 的请求。请先发送一个请求，等待其响应，仅在必要时再以相同密钥重试。使用相同密钥的并发请求不会被去重，并可能以 HTTP 500 失败。

选择幂等性密钥

密钥应该唯一标识预期的标签创建。良好的模式：

模式	示例	使用场景
订单 ID	`N-2026-05-27-TEST-03`	每个订单一个标签
订单 + 序号	`N-2026-05-27-TEST-03-1`	每个订单多个标签
UUID	`f47ac10b-58cc-4372-a567-0e02b2c3d479`	通用
订单 + 尝试次数	`N-2026-05-27-TEST-03-2`	失败标签后的重试（见下方）

遇到超时或暂时性服务器错误时，请重复使用原始 idempotencyKey 和未修改的请求体。修改请求体时必须使用新密钥。物流商端失败的标签（HTTP 502）请参阅「重试失败的标签」。

400 验证错误后，由于未创建标签，可以重复使用相同的 idempotencyKey。修正请求后使用相同密钥重试。

重试策略

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

设置请求超时

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

失败时等待再重试

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

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

使用与原始请求相同的 idempotencyKey 和未修改的请求体重试。即使原始请求已成功但响应丢失，也能获取已保存的结果。

限制重试次数

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

尝试 1: POST /labels → 超时
  等待 1 秒
尝试 2: POST /labels → 500
  等待 2 秒
尝试 3: POST /labels → 200（幂等重放 — 标签在尝试 1 时已创建）

重试失败的标签

失败的标签对其 idempotencyKey 而言是最终结果，且会保留其 customerOrderNumber。请先修正原因 — 地址、产品代码或账户配置。大多数物流商拒绝并非暂时性问题。接着发送一个新的请求，使用新的 idempotencyKey 和新的 customerOrderNumber（或省略以自动生成）。重复使用该编号会返回 409 DUPLICATE_CUSTOMER_ORDER_NUMBER。建议的模式：附加一个尝试次数后缀，例如 N-2026-05-27-TEST-03-2，同时使完整订单号保持在 40 个字符以内。请将您原始的订单参考保留在 order.orderNumbers.referenceNumbers 中。允许使用的字符请参阅客户订单号。失败标签所返回的错误内容，请参阅下游物流商错误 502 与 422。

各端点的幂等性

端点	幂等	机制
`POST /labels`	是	`idempotencyKey` 字段 — 每个请求中必填
`GET /labels/{id}`	是	只读 — 天然幂等
`GET /tracking/{id}`	是	只读 — 天然幂等

失败场景

收到响应前的网络超时

标签可能已创建，也可能未创建。请使用相同的 idempotencyKey 和未修改的请求体重试。如果已保存某次尝试的记录，API 会返回 HTTP 200 及该结果，包括任何已保存的失败结果。否则会再次尝试创建；成功则返回 HTTP 201。

HTTP 500 内部服务器错误

暂时性服务器错误。使用相同的 idempotencyKey 并以退避策略重试。

HTTP 502 错误网关（物流商错误）

物流商拒绝了请求。标签已在此 idempotencyKey 下以 status: failed 保存。使用相同密钥重试会以 HTTP 200 返回相同的失败结果，且不会再次联系物流商。若要重新尝试，请参阅「重试失败的标签」。

HTTP 400 验证错误

请求无效。未修正请求前请勿重试。由于未创建标签，修正请求体后可以重复使用相同的 idempotencyKey。

HTTP 409 冲突

请先查看 code。IDEMPOTENCY_CONFLICT 表示应使用原请求体，或为修改后的请求使用新密钥。DUPLICATE_CUSTOMER_ORDER_NUMBER 表示应获取现有标签，或选择其他订单号。

快速开始

指南

使用场景指南

平台

幂等性与重试

幂等性与重试

幂等性的工作方式

选择幂等性密钥

重试策略

重试失败的标签

各端点的幂等性

失败场景

​幂等性与重试

​幂等性的工作方式

​选择幂等性密钥

​重试策略

​重试失败的标签

​各端点的幂等性

​失败场景

幂等性与重试

幂等性的工作方式

选择幂等性密钥

重试策略

重试失败的标签

各端点的幂等性

失败场景