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

错误处理

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

错误响应格式

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

格式	发生时机	状态码
标准错误	身份验证、资源未找到、服务器错误	401, 403, 404, 405, 500
验证错误	请求体模式验证失败	400
标签失败	物流商拒绝标签请求	502（亦含 `status: failed` 的 201/200）

标准错误

用于身份验证失败、资源未找到和服务器错误：

{
  "error": "Unauthorized"
}

验证错误

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

{
  "error": "Validation failed",
  "details": [
    {
      "field": "shipment.shipTo.address.countryCode",
      "message": "must be a valid ISO 3166-1 alpha-2 country code"
    },
    {
      "field": "shipment.parcels[0].weight",
      "message": "must be greater than 0"
    }
  ]
}

details 中的每个条目包含：

字段	说明
`field`	指向无效字段的点分隔路径（数组索引使用括号表示法）
`message`	验证失败的人类可读描述

HTTP 状态码

状态	含义	发生时机	可重试
200	成功 / 幂等重放	GET 请求成功，或使用先前已用过的 `idempotencyKey` 的 POST	不适用
201	已创建	标签创建成功	不适用
400	错误请求	请求体验证失败	否 — 修正请求
401	未授权	`x-rr-apikey` / `x-rr-apitoken` 缺失或无效	否 — 至 User Portal 获取有效认证信息
403	禁止访问	认证信息有效但无权访问请求的资源	否 — 确认账户权限
404	未找到	标签 ID 或配送账户不存在	否 — 确认 ID
405	方法不允许	此端点不支持该 HTTP 方法	否 — 检查方法
500	内部服务器错误	非预期的服务器故障	是 — 使用退避策略重试
502	错误网关	物流商服务返回错误	是 — 使用退避策略重试

验证错误（400）

验证错误表示请求体不符合 API 模式的要求。响应一定包含带有具体字段路径的 details 数组。常见原因：

缺少必填字段（shipment.shipTo、courier、idempotencyKey）
字段格式无效（国家代码、电子邮件、电话号码）
数值无效（重量必须大于 0）

重试前请修正 details 数组中列出的所有验证错误。由于未创建标签，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

认证信息有效但无权访问请求的资源。当尝试获取属于其他账户的标签或追踪信息时会发生：

{
  "error": "Forbidden"
}

下游物流商错误（502）

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

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "courier": "yunexpress",
  "courierOrderNumber": null,
  "courierTrackingNumber": null,
  "error": {
    "code": "COURIER_ERROR",
    "message": "Address validation failed at courier"
  }
}

error 对象包含：

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

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

可重试与不可重试的错误

错误类型	可重试	处理方式
400 验证	否	根据 `details` 修正请求体
401 未授权	否	向 Flex Forward 团队获取有效令牌
403 禁止访问	否	确认对资源的账户访问权限
404 未找到	否	确认标签 ID 或配送账户
500 服务器错误	是	使用相同的 `idempotencyKey` 并以退避策略重试
502 物流商错误	视情况	检查错误消息 — 暂时性问题可重试，验证问题不可

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

故障排除

缺少 Content-Type 头部

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

基础 URL 错误或使用 HTTP

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

标签 ID 的 UUID 格式无效

GET /labels/{id} 和 GET /tracking/{id} 的 id 参数必须是有效的 UUID。传入追踪号码或其他标识符格式将返回 404 错误。

标签已创建但状态为 failed

HTTP 201 或 200 响应中的 status: failed 表示标签已保存但物流商拒绝了请求。请检查 error 对象中的物流商错误消息。常见原因：无效地址、不支持的目的地，或物流商账户配置问题。

快速开始

指南

使用场景指南

平台

错误处理

错误处理

错误响应格式

标准错误

验证错误

HTTP 状态码

验证错误（400）

身份验证错误（401 / 403）

401 Unauthorized

403 Forbidden

下游物流商错误（502）

可重试与不可重试的错误

故障排除

​错误处理

​错误响应格式

​标准错误

​验证错误

​HTTP 状态码

​验证错误（400）

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

​401 Unauthorized

​403 Forbidden

​下游物流商错误（502）

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

​故障排除

错误处理

错误响应格式

标准错误

验证错误

HTTP 状态码

验证错误（400）

身份验证错误（401 / 403）

401 Unauthorized

403 Forbidden

下游物流商错误（502）

可重试与不可重试的错误

故障排除