> ## Documentation Index
> Fetch the complete documentation index at: https://openapidocs.flexforwardship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 幂等性与重试

> 如何安全地重试请求并防止重复创建标签

<Note>
  此页面由英文翻译而成。[英文版](/introduction)为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。
</Note>

# 幂等性与重试

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

## 幂等性的工作方式

`POST /labels` 端点使用 `idempotencyKey` 字段来确保每个标签创建请求只会被处理一次。

**第一次请求** — API 创建标签并返回 HTTP 201：

```bash theme={null}
curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "N-2026-05-27-TEST-03",
    "courier": "yunexpress",
    ...
  }'
```

```json 201 Created theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
```

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

```json 200 OK（幂等重放） theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
```

幂等性密钥的范围限于您的 API 账户。不同账户可以使用相同的密钥而不会冲突。

## 选择幂等性密钥

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

| 模式      | 示例                                     | 使用场景     |
| ------- | -------------------------------------- | -------- |
| 订单 ID   | `N-2026-05-27-TEST-03`                 | 每个订单一个标签 |
| 订单 + 序号 | `N-2026-05-27-TEST-03-1`               | 每个订单多个标签 |
| UUID    | `f47ac10b-58cc-4372-a567-0e02b2c3d479` | 通用       |

<Warning>
  重试相同的逻辑请求时，绝不要生成新的 `idempotencyKey`。请重复使用原始密钥，以便 API 能检测重复。
</Warning>

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

## 重试策略

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

<Steps>
  <Step title="设置请求超时">
    为 HTTP 请求设置合理的超时时间（例如 30 秒）。
  </Step>

  <Step title="失败时等待再重试">
    使用指数退避：1 秒、2 秒、4 秒、8 秒。
  </Step>

  <Step title="重复使用相同的幂等性密钥">
    始终使用与原始请求相同的 `idempotencyKey` 重试。即使原始请求已成功但响应丢失，也能确保不会创建重复标签。
  </Step>

  <Step title="限制重试次数">
    在 3–5 次重试后停止。如果请求仍然失败，记录错误并升级调查。
  </Step>
</Steps>

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

## 各端点的幂等性

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

## 失败场景

<AccordionGroup>
  <Accordion title="收到响应前的网络超时">
    标签可能已创建也可能未创建。使用相同的 `idempotencyKey` 重试。如果标签已创建，API 会返回 HTTP 200 和原始结果。如果未创建，API 会创建标签并返回 HTTP 201。
  </Accordion>

  <Accordion title="HTTP 500 内部服务器错误">
    暂时性服务器错误。使用相同的 `idempotencyKey` 并以退避策略重试。
  </Accordion>

  <Accordion title="HTTP 502 错误网关（物流商错误）">
    物流商服务返回错误。标签以 `status: failed` 保存。重试前请检查错误消息 — 部分物流商错误需要修改请求（如无效地址）。对于暂时性的物流商问题，使用相同的 `idempotencyKey` 重试。
  </Accordion>

  <Accordion title="HTTP 400 验证错误">
    请求无效。未修正请求前请勿重试。由于未创建标签，修正请求体后可以重复使用相同的 `idempotencyKey`。
  </Accordion>
</AccordionGroup>