响应与错误处理

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

{
  "code": 200,
  "msg": "成功",
  "data": { ...业务数据... },
  "timeStamp": 1788830174812
}

`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`

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

调用方应按响应体中的 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` 反馈排查

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

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

建立生产环境排错记录。

按参数、认证、权限和响应解析逐项定位问题。