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

# 响应与错误处理

> 解析统一响应，并正确处理参数、认证、权限、限流和平台错误。

AIBase 使用统一外层响应结构。业务结果位于 `data.result`，`data.requestId` 用于请求追踪。

## 成功响应

```json theme={null}
{
  "code": 200,
  "msg": "成功",
  "data": {
    "result": {},
    "requestId": "599b2f8f39078d"
  },
  "timeStamp": 1788830174812
}
```

| 字段               | 类型            | 说明                     |
| ---------------- | ------------- | ---------------------- |
| `code`           | integer       | 业务状态码；`200` 表示成功       |
| `msg`            | string        | 返回消息                   |
| `data`           | object 或 null | 业务返回数据；发生错误时可能为 `null` |
| `data.result`    | object        | 由具体 `apiCode` 定义的业务结果  |
| `data.requestId` | string        | 本次请求的追踪标识              |
| `timeStamp`      | long          | 服务端返回时间戳，单位为毫秒         |

## 错误码

调用方应同时检查 HTTP 状态码与响应体中的业务 `code`，不要只根据 `msg` 文本判断结果。

| 状态码   | 含义                 | 是否直接重试 | 开发者处理动作                          |
| ----- | ------------------ | ------ | -------------------------------- |
| `200` | 请求成功               | 不需要    | 继续校验业务 `code` 并读取 `data.result`  |
| `400` | 请求参数错误或格式不正确       | 否      | 检查 `apiCode`、`data`、JSON 格式和字段类型 |
| `401` | API Key 无效、缺失或认证失败 | 否      | 检查 Header、密钥完整性和有效期              |
| `403` | 无权调用当前能力           | 否      | 检查密钥权限、账号权限和 IP 白名单              |
| `429` | 请求超过当前调用限制         | 有限重试   | 降低频率，等待后按指数退避策略重试                |
| `500` | 平台服务异常             | 有限重试   | 保留调用时间和请求标识，稍后重试                 |

```json theme={null}
{
  "code": 400,
  "msg": "请求参数错误",
  "data": null,
  "timeStamp": 1788830174812
}
```

<Warning>
  实际错误码及错误信息以平台返回结果为准。错误响应中的 `data` 可能为 `null`，解析时必须做好空值兼容。
</Warning>

## HTTP 状态与业务 code

HTTP 状态描述传输和服务处理结果；响应体中的 `code` 描述业务调用结果。客户端需要依次校验这两层，任何一层失败都不应继续读取 `data.result`。

```javascript theme={null}
async function parseAIBaseResponse(response) {
  const text = await response.text();
  let payload;

  try {
    payload = JSON.parse(text);
  } catch {
    throw new Error(`AIBase 返回了非 JSON 响应，HTTP ${response.status}`);
  }

  if (!response.ok) {
    throw new Error(`AIBase HTTP ${response.status}: ${payload.msg ?? "未知错误"}`);
  }

  if (payload.code !== 200) {
    throw new Error(`AIBase 业务错误 ${payload.code}: ${payload.msg ?? "未知错误"}`);
  }

  return payload.data;
}
```

<Note>
  “有限重试”是推荐的客户端恢复策略，不代表平台承诺固定的重试次数或等待时间。当前重试上限应由调用方结合业务容错要求设置。
</Note>

## 推荐处理顺序

<Steps>
  <Step title="检查网络与 HTTP 状态">
    先处理连接失败、超时、空响应和非 2xx HTTP 状态。
  </Step>

  <Step title="检查业务 code">
    HTTP 请求完成后，再判断响应体中的 `code` 是否为 `200`。
  </Step>

  <Step title="记录 requestId">
    在成功响应中记录 `data.requestId`；发生异常时同时保留请求时间和 `apiCode`。
  </Step>

  <Step title="按错误类型恢复">
    参数和凭证问题应修正后再请求；限流和平台异常可采用有限次数重试。
  </Step>
</Steps>

<Columns cols={2}>
  <Card title="调用限制" icon="timer-reset" href="/platform/rate-limits">
    查看超时、并发、有限重试和指数退避建议。
  </Card>

  <Card title="requestId 请求追踪" icon="fingerprint" href="/platform/request-id">
    建立生产环境排错记录。
  </Card>

  <Card title="联调排错清单" icon="list-checks" href="/platform/troubleshooting">
    按请求、认证、权限和响应解析逐项定位问题。
  </Card>
</Columns>