# 调用常见问题

## 从哪里查看接口和参数？

在 [数据接口目录](../data/index.rst) 查找数据类别和字段说明，在 [Swagger](https://quantsource.cc/api/docs) 查看实际可调用的 HTTP 接口、参数类型、默认值和必填项。`https://quantsource.cc/docs/` 是用户手册，`https://quantsource.cc/api/docs` 是在线调试入口。

## 返回 422 怎么处理？

先检查参数名是否拼写正确、必填项是否齐全，再根据错误响应中的 `detail` 和 `loc` 定位字段。股票代码需要保留前导零；日期要符合接口格式，并且是有效日期。

例如，`stock_zh_a_hist` 的 `period` 只接受 `daily`、`weekly`、`monthly`；`adjust` 为留空、`qfq` 或 `hfq`。开始日期不得晚于结束日期，`timeout` 必须为有限正数。不要把空参数或 `None` 写成字符串 `"None"`。

## HTTP 200，但返回空数组怎么办？

空表可能返回 `[]`。请核对标的代码、数据覆盖范围、交易日期和查询条件，并尝试文档中的参数组合。不同接口的数据来源和历史范围不同，没有数据不一定表示客户端调用失败。

## 请求超时或返回 502 怎么办？

检查客户端网络与超时设置，缩小查询范围，并在稍后适度重试。上游网站可能暂时不可用、限流或改变数据格式。避免持续高频重试。

接口参数中的 `timeout`（仅适用于支持该参数的接口）与客户端自身的等待超时是两项设置。例如 `requests.get(..., params={"timeout": 10}, timeout=30)` 分别表示上游请求超时参数和客户端等待时间。

## 股票价格、日期或单位看起来不一致？

先核对接口来源、复权方式、频率及字段单位。后复权历史价格可能出现负值，不能只按数值正负判断接口是否错误。处理前应结合具体接口的数据说明与研究用途确认。

## 是否需要 API Key？

当前 `/api/public/*` 未要求 API Key。`/api/private/*` 的认证尚未开放，调用会返回 `501`。请按当前公开接口说明接入。

## 如何反馈调用问题？

记录接口名、已脱敏的查询参数、请求时间、HTTP 状态码和响应中的 `request_id`（如有），通过 [项目 Issues](https://github.com/lisuotian/quantsource/issues) 反馈。不要提交 Cookie、令牌或其他账号凭据。