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

# 响应与错误处理

> 解析 GEOBase 统一响应结构，并正确处理成功、空数据与各类错误码。

平台采用统一外层响应结构，业务数据位于 `data` 字段。GEOBase 全部接口为 SYNC 实时请求，`data` 即最终业务结果。

```json theme={null}
{
  "code": 200,
  "msg": "成功",
  "data": { ...业务数据... },
  "timeStamp": 1788830174812
}
```

| 字段 | 中文名 | 类型 | 说明 |
| - | - | - | - |
| `code` | 状态码 | integer | `200` 表示成功，其余为业务或系统错误码 |
| `msg` | 提示消息 | string | 本次调用的结果描述，随请求语言环境返回对应语言 |
| `data` | 业务数据 | object 或 null | 业务结果，结构由各 `apiCode` 对应业务决定 |
| `timeStamp` | 时间戳 | long | 服务端响应时间戳，单位为毫秒 |

## `data` 的四种结构形态

不同 `apiCode` 的 `data` 结构不同，接入前请先确认目标接口的形态：

| 形态 | 说明 | 适用接口 |
| - | - | - |
| 分页结构 | 含 `records` 数组与 `total` / `size` / `current` / `pages` | `geo.brand`、`geo.competitors`、`brand.prompt`、`prompt.analysis.detail`、`source.citation.list` |
| 数组结构 | 直接为对象数组 | `brand.topic`、`prompt.analysis.overview`、`llm.comparison` |
| 对象结构 | 含固定字段的对象 | `brand.overview`（含 `brand` 与 `competitor`） |
| 分组结构 | 按名称分组，键为动态值、值为统计数组 | `llm.trend`、`llm.topic`、`llm.intention`、`llm.prompt` |

<Note>
  部分接口固定返回全量数据（`size = -1`），无需也支持传入分页参数；另有部分接口支持 `pageNo` / `pageSize`。请以具体接口页面的参数说明为准。
</Note>

## 错误码

调用方应按响应体中的 `code` 处理对应分支。

| code | 含义 | 说明与处理建议 |
| - | - | - |
| `200` | 成功 | 调用成功，读取 `data` |
| `2001` | 暂无数据 | 未查询到业务数据，按空结果处理 |
| `4001` | 所需参数不足 | `AIBase-API-Key` 为空、请求体为空或 `apiCode` 为空；补充必填参数后重试 |
| `4002` | 参数错误 / API 不存在 | 请求参数不合法，或 `apiCode` 对应的 API 不存在、已禁用；核对 `apiCode` |
| `403` | 未授权 | `AIBase-API-Key` 无效、已过期、客户端 IP 不在白名单，或该 Key 未被授予该 API 调用权限 |
| `4021` | 品牌不存在 | 按 `brandId` 查询不到品牌，核实品牌 ID |
| `500` | 系统异常 | 服务端执行异常，建议稍后重试，并携带 `AIBase-Request-Id` 反馈排查 |

```json theme={null}
{
  "code": 4001,
  "msg": "所需参数不足",
  "data": null,
  "timeStamp": 1788830174812
}
```

<Warning>
  调用方应同时关注 HTTP 状态码与响应体中的业务状态码 `code`，不建议仅根据 `msg` 文本判断调用是否成功。错误响应中的 `data` 可能为 `null`，解析时必须做好空值兼容。
</Warning>

## 推荐处理顺序

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

  <Step title="检查业务 code">
    HTTP 请求完成后，再判断响应体中的 `code` 是否为 `200`；`2001` 按空结果处理，不要当成失败。
  </Step>

  <Step title="记录请求标识">
    生产环境记录 `AIBase-Request-Id`；异常时同时保留 `apiCode`、请求参数与响应时间。
  </Step>

  <Step title="按错误类型恢复">
    参数与凭证问题（`4001` / `4002` / `403` / `4021`）应先修正再请求；`500` 可稍后有限重试。
  </Step>
</Steps>

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.