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

错误处理

Flex Forward API 使用标准 HTTP 状态码和结构化的错误响应。本页面涵盖错误格式、状态码含义以及处理失败的指引。

错误响应格式

API 根据失败类型返回四种错误响应格式。了解预期的格式有助于编写正确的错误解析逻辑。

格式	发生时机	状态码
标准错误	不支持的物流商/产品、身份验证、资源未找到、冲突、速率限制或服务器错误	400, 401, 403, 404, 409, 429, 500；GET 端点上为 502
验证错误	请求体模式验证失败	400
标签失败	物流商拒绝标签请求；`status: failed` 的 `LabelResponse`	`POST /labels` 的 502，或幂等重放返回已保存的失败结果时的 200
失败标签读取	读取物流商提交失败的标签；`LabelFailedResponse`	`GET /labels/{id}` 与 `GET /tracking/{id}` 的 422

标准错误

用于不支持的物流商/产品、身份验证失败、冲突、资源未找到和服务器错误等失败情形。格式为 { "error": string, "code"?: string }：

{
  "error": "Label not found"
}

error 文本仅供参考，可能随时变更且不另行通知。请根据 HTTP 状态码，以及存在时的 code，来判断分支逻辑 — 切勿依赖消息文本本身。 code 字段会在部分错误响应中提供。IDEMPOTENCY_CONFLICT 与 DUPLICATE_CUSTOMER_ORDER_NUMBER 可区分 HTTP 409 冲突。

`code`	含义
`IDEMPOTENCY_CONFLICT`	HTTP 409：该密钥已用于不同的请求体。使用原请求体进行重放，或为已更改的请求使用新密钥。
`DUPLICATE_CUSTOMER_ORDER_NUMBER`	HTTP 409：该订单号已存在于您的账户中。请获取该标签，或为新标签使用不同的订单号。
`COURIER_ERROR`	物流商拒绝了标签请求。此代码在 HTTP 502 的标签响应中嵌套于 `error.code` 下，或在失败标签读取中以 `errorCode` 返回。

code 字段为可选，且此列表并非详尽无遗。没有代码的错误请依 HTTP 状态码处理，并容忍未知的代码值。

验证错误

用于请求验证失败（HTTP 400）。包含带有字段级别错误信息的 details 数组：

{
  "error": "Validation failed",
  "details": [
    {
      "field": "shipment.parcels.0.weight",
      "message": "must be >= 0"
    }
  ]
}

details 中的每个条目包含：

字段	说明
`field`	指向无效字段的点分隔路径。数组索引以点分隔的数字表示，例如 `shipment.parcels.0.weight`。
`message`	验证失败的人类可读描述

仅会返回第一个验证错误。修正后重新发送即可看到下一个错误。 HTTP 400 也可能使用标准错误格式，例如在物流商或产品不受支持时。读取 details 前请先确认其是否存在；不要假设每个 400 响应都包含字段级错误。

HTTP 状态码

状态	含义	发生时机	可重试
200	成功 / 幂等重放	GET 请求成功，或 `POST /labels` 使用相同密钥与请求体进行重放。保存的结果可能为 `status: failed`	不适用
201	已创建	标签创建成功	不适用
400	错误请求	请求验证失败或不支持的物流商/产品	否 — 有 `details` 时先查看，否则查看 `error` 与 `code` 后修正
401	未授权	`x-rr-apikey` / `x-rr-apitoken` 缺失或无效	否 — 至 User Portal 获取有效认证信息
403	禁止访问	认证信息有效但账户不被允许（例如被封禁）	否 — 确认账户权限
404	未找到	标签 ID 或配送账户不存在	否 — 确认 ID
409	冲突	以不同请求体重复密钥，或订单号重复	否 — 根据 `code` 使用原请求体/新密钥，或选择其他订单号
422	无法处理的实体	标签存在但物流商提交失败；无文件或追踪数据可用（`GET /labels/{id}`、`GET /tracking/{id}`）	否 — 创建新标签
429	请求过多	已超出账户的请求速率上限。所有端点均已声明此响应，以便客户端在正式启用前实现相应处理（请参阅速率限制）	是 — 等待 `Retry-After` 头部中的秒数后再重试
500	内部服务器错误	非预期的服务器故障	是 — 使用退避策略重试
502	错误网关	物流商拒绝标签请求；标签以 `status: failed` 保存	使用相同 `idempotencyKey` 不可 — 请先修正原因，再发送新请求（参阅重试失败的标签）

标签创建结果的判读

POST /labels 在 200、201 与 502 时都返回相同的 LabelResponse 结构。HTTP 状态码说明这次调用是创建了标签、重放了先前的尝试，还是被物流商拒绝。status 字段则说明标签是否存在。

在 POST /labels 上，请根据 status 字段而不是 HTTP 状态码进行分支处理。即使第一次尝试在物流商端失败，幂等重放仍会返回 HTTP 200，因此 200 响应可能带有 status: failed。

HTTP	`status`	`error`	含义	处理方式
201	`created`	`null`	这次调用已在物流商端创建标签	保存 `id`，继续进行文件获取与跟踪
200	`created`	`null`	重放先前成功的尝试	与 201 相同 — 未创建新标签
200	`failed`	对象	重放先前被物流商拒绝的尝试	请勿以相同密钥重试；参阅重试失败的标签
502	`failed`	对象	物流商拒绝了该请求；此次尝试已绑定到您的 `idempotencyKey` 保存	读取 `error.message`，修正请求，再以新的 `idempotencyKey` 与 `customerOrderNumber` 重新发送

验证错误（400）

模式验证错误表示请求体不符合 API 的要求，并包含带有具体字段路径的 details 数组。其他 HTTP 400 错误使用不含 details 的标准错误格式。常见原因：

缺少必填字段（shipment.shipTo、courier、idempotencyKey）
字段类型或长度错误（例如 countryCode 必须恰好为 2 个字符）
数值为负（weight 与尺寸不得为负数）
order.customerOrderNumber 无效（最多 40 个字符，只能使用 ASCII 字母、数字、-、_）
不支持的 label.format（请使用 PDF 或 PNG）或商品 unitPrice.currency（仅接受 USD）

重试前请修正报告的错误。由于未创建标签，400 响应后可以重复使用相同的 idempotencyKey。

身份验证错误（401 / 403）

401 Unauthorized

x-rr-apikey 或 x-rr-apitoken 头部缺失或无效：

{
  "error": "unauthorized"
}

请确认两个头部均存在：

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN

403 Forbidden

认证信息有效，但账户不被允许调用 API（例如被封禁的账户）：

{
  "error": "Forbidden: account is blocked"
}

属于其他账户的标签或追踪记录会返回 404，而非 403。

下游物流商错误 502 与 422

当 POST /labels 执行期间物流商服务返回错误时，API 以 HTTP 502 响应。标签会以 status: failed 保存在数据库中，并包含物流商的错误详情：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "failed",
  "courier": "yunexpress",
  "courierOrderNumber": null,
  "courierTrackingNumber": null,
  "error": {
    "code": "COURIER_ERROR",
    "message": "Address validation failed at courier"
  }
}

error 对象包含：

字段	说明
`code`	机器可读的错误代码
`message`	来自物流商的人类可读错误描述

502 响应表示标签请求已到达物流商并被拒绝。重试前请检查错误消息 — 部分物流商错误（如地址验证）并非暂时性的，需要修改请求。

之后对失败标签调用 GET /labels/{id} 或 GET /tracking/{id} 时，会返回 HTTP 422 及 LabelFailedResponse 内容 — 该标签无文件或追踪数据可用：

{
  "error": "Label creation failed",
  "errorCode": "COURIER_ERROR",
  "errorMessage": "Address validation failed at courier"
}

可重试与不可重试的错误

错误类型	可重试	处理方式
400 错误请求	否	有 `details` 时先查看，否则查看 `error` 与 `code` 后修正
401 未授权	否	至 User Portal（Settings → Signing Key and API Token）获取有效认证信息
403 禁止访问	否	确认对资源的账户访问权限
404 未找到	否	确认标签 ID 或配送账户
409 冲突	否	对于 `IDEMPOTENCY_CONFLICT`，使用原请求体或新密钥；对于 `DUPLICATE_CUSTOMER_ORDER_NUMBER`，获取现有标签或选择其他订单号
422 无法处理的实体	否	标签的物流商提交失败 — 创建新标签
429 请求过多	是	等待 `Retry-After` 秒后，使用相同的 `idempotencyKey` 重试
500 服务器错误	是	使用相同的 `idempotencyKey` 并以退避策略重试
502 物流商错误	使用相同密钥不可	请先修正原因，再以新的 `idempotencyKey` 与 `customerOrderNumber` 发送新请求 — 参阅重试失败的标签

推荐的重试策略请参阅幂等性与重试。

故障排除

缺少 Content-Type 头部

所有 POST 请求必须包含 Content-Type: application/json。缺少时请求体将不会被解析，API 会返回 400 错误。

基础 URL 错误或使用 HTTP

所有请求必须使用 HTTPS。请确认使用正确的环境 URL：https://api.flexforwardship.com（生产）或 https://sandbox.flexforwardship.com（开发）。

找不到标识符

GET /labels/{id} 和 GET /tracking/{id} 的 id 参数接受标签 UUID 或您的 customerOrderNumber。传入其他值，或属于其他账户的标识符，将返回 404 错误。

标签已创建但状态为 failed

status: failed 的响应会由 POST /labels 以 HTTP 502 返回（若以相同 idempotencyKey 重放则为 HTTP 200），之后读取该标签则会返回 HTTP 422。请检查 error 对象（读取时为 LabelFailedResponse 内容）中的物流商错误消息。常见原因：无效地址、不支持的目的地，或物流商账户配置问题。

快速开始

指南

使用场景指南

平台

错误处理

错误处理

错误响应格式

标准错误

验证错误

HTTP 状态码

标签创建结果的判读

验证错误（400）

身份验证错误（401 / 403）

401 Unauthorized

403 Forbidden

下游物流商错误 502 与 422

可重试与不可重试的错误

故障排除

​错误处理

​错误响应格式

​标准错误

​验证错误

​HTTP 状态码

​标签创建结果的判读

​验证错误（400）

​身份验证错误（401 / 403）

​401 Unauthorized

​403 Forbidden

​下游物流商错误 502 与 422

​可重试与不可重试的错误

​故障排除

错误处理

错误响应格式

标准错误

验证错误

HTTP 状态码

标签创建结果的判读

验证错误（400）

身份验证错误（401 / 403）

401 Unauthorized

403 Forbidden

下游物流商错误 502 与 422

可重试与不可重试的错误

故障排除