跳转到主要内容

​
错误处理

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未授权Bearer 令牌缺失或无效否 — 向 Flex Forward 团队获取有效令牌
403禁止访问令牌有效但无权访问请求的资源否 — 确认账户权限
404未找到标签 ID 或配送账户不存在否 — 确认 ID
405方法不允许此端点不支持该 HTTP 方法否 — 检查方法
500内部服务器错误非预期的服务器故障是 — 使用退避策略重试
502错误网关物流商服务返回错误是 — 使用退避策略重试

​
验证错误（400）

验证错误表示请求体不符合 API 模式的要求。响应一定包含带有具体字段路径的 details 数组。 常见原因：
  • 缺少必填字段（shipment.shipTo、courier、idempotencyKey）
  • 字段格式无效（国家代码、电子邮件、电话号码）
  • 数值无效（重量必须大于 0）
重试前请修正 details 数组中列出的所有验证错误。由于未创建标签，400 响应后可以重复使用相同的 idempotencyKey。

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

​
401 Unauthorized

Bearer 令牌缺失、格式不正确或已过期： 
{
  "error": "Unauthorized"
}
请确认 Authorization 头部存在且格式正确：Bearer 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 物流商错误视情况检查错误消息 — 暂时性问题可重试，验证问题不可
推荐的重试策略请参阅幂等性与重试。

​
故障排除

所有 POST 请求必须包含 Content-Type: application/json。缺少时请求体将不会被解析，API 会返回 400 错误。
所有请求必须使用 HTTPS。请确认使用正确的环境 URL：https://api.flexforward.com（生产）或 https://sandbox.flexforward.com（开发）。
GET /labels/{id} 和 GET /tracking/{id} 的 id 参数必须是有效的 UUID。传入追踪号码或其他标识符格式将返回 404 错误。
HTTP 201 或 200 响应中的 status: failed 表示标签已保存但物流商拒绝了请求。请检查 error 对象中的物流商错误消息。常见原因：无效地址、不支持的目的地，或物流商账户配置问题。