调用常见问题

从哪里查看接口和参数？

在 数据接口目录 查找数据类别和字段说明，在 Swagger 查看实际可调用的 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 反馈。不要提交 Cookie、令牌或其他账号凭据。