> ## 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 开发者 API 调用问题。

按以下顺序排查，可覆盖绝大多数联调问题。每一节都给出对应错误码与验证动作。

## 1. 返回 403（未授权）

依次检查以下四项：

1. `AIBase-API-Key` 是否有效（是否复制完整、有无多余空格）。
2. Key 是否已过期。
3. 客户端出口 IP 是否在 Key 的 IP 白名单内（未配置白名单时默认放行）。
4. 该 Key 是否被授予目标 `apiCode` 的调用权限（仅在 Key 开启权限限制时校验）。

<Note>
  服务端校验顺序为：Key 有效性 → 有效期 → IP 白名单 → `apiCode` 是否存在且启用 → 调用权限。任一环节不通过都会返回 `403` 或 `4002`。
</Note>

## 2. 返回 4001（所需参数不足）

常见原因：`AIBase-API-Key` 为空、请求体为空、`apiCode` 为空，或某个接口的必填业务参数缺失。

* 多数业务接口要求 `data.brandId` 必填，缺失即返回 `4001`。
* 先调用[品牌列表查询](/geobase-api/api-reference/brand-list)拿到有效的 `brandId`，再调用其他接口。

## 3. 返回 4002（参数错误 / API 不存在）

* 核对 `apiCode` 拼写，确认它与目标接口文档一致。
* 确认该 `apiCode` 对应的 API 仍处于启用状态。
* 检查业务参数类型与取值，例如分页接口的 `pageSize` 超过上限会被自动截断而非报错。

<Tip>
  `geo.brand` 在两套文档中存在同名差异：GEOBase 本套文档的 `geo.brand` 是品牌列表查询（入口 `/v1/openapi/execute`），而 [AIBase 开发者文档](/api-reference/brand-score) 的 `geo.brand` 是品牌得分检测（入口 `/v1/openapi/tasks`）。弄错会导致 `4002` 或返回结构不符。
</Tip>

## 4. 返回 4021（品牌不存在）

按 `brandId` 查询不到品牌。请用[品牌列表查询](/geobase-api/api-reference/brand-list)核对当前 Key 所属账号下的真实品牌 ID —— 品牌是账号级资源，换 Key 后品牌 ID 也会不同。

## 5. 返回 2001（暂无数据）

这不是调用失败，而是业务上未查询到数据，应按空结果处理。常见场景：

* 时间范围内该品牌尚未产生监测数据。
* 筛选条件过窄（如指定了某个 AI 平台或情感类型）。
* 分组结构接口无数据时，`llm.intention` 返回空数组 `[]`，`llm.prompt` 返回空对象。

## 6. 返回 500（系统异常）

服务端执行异常。建议稍后有限重试，并携带 `AIBase-Request-Id`、`apiCode`、请求参数与调用时间反馈排查。

## 7. 时间范围相关

带 `startDate` / `endDate` 的接口遵循统一规则：

* 不传时默认查询最近 7 天。
* `endDate` 晚于今天会被自动截断为今天。
* 起止时间跨度最大 6 个月。
* 开始日期晚于结束日期将直接报错。

## 8. 解析结果不符合预期

按 `data` 的四种形态分别处理，不要用同一套解析逻辑套所有接口：

| 形态 | 适用接口 | 解析要点 |
| - | - | - |
| 分页结构 | `geo.brand`、`geo.competitors`、`brand.prompt`、`prompt.analysis.detail`、`source.citation.list` | 读取 `data.records`；部分接口 `size = -1` 表示返回全量 |
| 数组结构 | `brand.topic`、`prompt.analysis.overview`、`llm.comparison` | `data` 直接是数组 |
| 对象结构 | `brand.overview` | `data` 含 `brand` 与 `competitor` 两部分 |
| 分组结构 | `llm.trend`、`llm.topic`、`llm.intention`、`llm.prompt` | 键为动态名称（平台名 / 主题名 / 意图名 / 问题文本），值为统计数组 |

## 9. 本地联调

本地开发环境服务端口为 `6006`，可直接调用 `http://localhost:6006/v1/openapi/execute`；生产环境替换为 `https://geobaseapi.aibase.com`。

<Warning>
  若出现超时，先确认客户端超时设置。实时接口耗时随业务量变化，建议超时不小于 60 秒。
</Warning>


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