> ## 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.

# 错误处理

> HTTP 状态码、错误响应格式与故障排除指南

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

# 错误处理

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

## 错误响应格式

API 根据失败类型返回两种错误响应格式。

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

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

### 标准错误

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

```json theme={null}
{
  "error": "Unauthorized"
}
```

### 验证错误

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

```json theme={null}
{
  "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）

<Note>
  重试前请修正 `details` 数组中列出的所有验证错误。由于未创建标签，400 响应后可以重复使用相同的 `idempotencyKey`。
</Note>

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

### 401 Unauthorized

Bearer 令牌缺失、格式不正确或已过期：

```json theme={null}
{
  "error": "Unauthorized"
}
```

请确认 `Authorization` 头部存在且格式正确：`Bearer YOUR_API_TOKEN`。

### 403 Forbidden

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

```json theme={null}
{
  "error": "Forbidden"
}
```

## 下游物流商错误（502）

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

```json theme={null}
{
  "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` | 来自物流商的人类可读错误描述 |

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

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

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

推荐的重试策略请参阅[幂等性与重试](/zh-Hans/idempotency-and-retries)。

## 故障排除

<AccordionGroup>
  <Accordion title="缺少 Content-Type 头部">
    所有 POST 请求必须包含 `Content-Type: application/json`。缺少时请求体将不会被解析，API 会返回 400 错误。
  </Accordion>

  <Accordion title="基础 URL 错误或使用 HTTP">
    所有请求必须使用 HTTPS。请确认使用正确的环境 URL：`https://api.flexforward.com`（生产）或 `https://sandbox.flexforward.com`（开发）。
  </Accordion>

  <Accordion title="标签 ID 的 UUID 格式无效">
    `GET /labels/{id}` 和 `GET /tracking/{id}` 的 `id` 参数必须是有效的 UUID。传入追踪号码或其他标识符格式将返回 404 错误。
  </Accordion>

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