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

当请求失败或结果不符合预期时，请先记录发生时间、HTTP 状态、业务 `code`、`apiCode` 和 `requestId`，再按照本页顺序检查。

<Warning>
  排错截图、终端输出和工单内容中不要包含完整 API Key。展示 Header 时请对密钥中间部分做脱敏处理。
</Warning>

## 一分钟预检

* 请求方法为 `POST`。
* 请求地址为 `https://api.aibase.cn/v1/openapi/tasks`。
* `AIBase-API-Key` 位于请求 Header，而不是 Query 或请求体。
* `Content-Type` 为 `application/json`。
* `apiCode` 为 `geo.questions_corr_recommend`。
* `data.keyword` 存在且不为空。
* 请求体是合法 JSON，没有多余逗号或错误引号。

## 按现象定位

| 现象               | 优先检查                                  | 下一步                       |
| ---------------- | ------------------------------------- | ------------------------- |
| 无法建立连接或超时        | 域名解析、服务器出网策略、代理和客户端超时                 | 保留调用时间，确认网络后有限重试          |
| `400`            | `apiCode`、`data.keyword`、JSON 格式和字段类型 | 修正请求后重新发送                 |
| `401`            | Header 名、API Key 完整性和有效期              | 更换有效密钥后重新发送               |
| `403`            | 密钥权限、账号权限和 IP 白名单                     | 在开发者 API 页面核对配置           |
| `429`            | 当前账号调用限制和瞬时并发                         | 降低频率并采用指数退避               |
| `500`            | 调用时间、`apiCode`、响应内容和请求标识              | 有限重试；持续出现时整理排错信息          |
| HTTP 正常但业务失败     | 响应体中的 `code` 和 `msg`                  | 按业务错误处理，不读取 `data.result` |
| 返回数组为空           | 业务 `code`、关键词和原始响应                    | 空数组可以是有效结果，避免按异常处理        |
| `hotValue` 为 `0` | 业务 `code` 和数组内容                       | `0` 不表示接口调用失败             |

## 检查原始 HTTP 结果

联调时可以先将响应体保存到文件，并单独输出 HTTP 状态。以下命令不会打印请求 Header，可减少密钥出现在终端记录中的风险。

```bash theme={null}
curl --silent --show-error \
  --output aibase-response.json \
  --write-out 'HTTP %{http_code}\n' \
  --request POST \
  --url https://api.aibase.cn/v1/openapi/tasks \
  --header "AIBase-API-Key: ${AIBASE_API_KEY}" \
  --header "AIBase-Request-Id: troubleshoot-$(date +%s)" \
  --header 'Content-Type: application/json' \
  --data '{
    "apiCode": "geo.questions_corr_recommend",
    "data": { "keyword": "多智能体系统" }
  }'
```

检查 `aibase-response.json` 时，依次确认：响应是合法 JSON、业务 `code` 为 `200`、`data` 不为空、需要的数组字段存在。

## 排错记录模板

持续失败时，整理以下信息可以减少重复沟通：

```text theme={null}
接口：AI 对话问题挖掘
请求时间：YYYY-MM-DD HH:mm:ss（时区）
请求地址：https://api.aibase.cn/v1/openapi/tasks
apiCode：geo.questions_corr_recommend
HTTP 状态：
业务 code：
业务 msg：
requestId：
是否稳定复现：
已完成的检查：
```

<Info>
  错误响应中的 `data` 可能为 `null`，因此不保证每次失败都能从 `data.requestId` 取得请求标识。此时请保留客户端传入的 `AIBase-Request-Id` 和准确请求时间。
</Info>

<Columns cols={2}>
  <Card title="响应与错误处理" icon="triangle-alert" href="/quickstart/response-errors">
    查看状态码、恢复动作和解析顺序。
  </Card>

  <Card title="requestId 请求追踪" icon="fingerprint" href="/platform/request-id">
    设计生产环境日志关联字段。
  </Card>
</Columns>