版本 v1.4
最后更新:2026-11-13
错误码与限流|HTTP 状态与重试策略 - FTLib
错误处理的目标不是“重试所有失败”,而是区分可恢复与不可恢复错误。鉴权失败、参数错误通常不应重试;限流与临时网络错误可以按退避策略重试。
错误响应
错误响应仍使用统一封装。code 非 0,message 为可读说明,request_id 用于定位请求。
json
{
"code": 40001,
"message": "invalid symbol format",
"request_id": "req_9a0f21c4",
"data": null
}
HTTP 状态码
| 状态码 | 含义 | 是否重试 |
|---|---|---|
| 200 | 请求完成,需检查业务 code | 否 |
| 400 | 参数或代码格式错误 | 否,修正请求 |
| 401 | 未鉴权或密钥无效 | 否 |
| 403 | 无权限或超出授权范围 | 否 |
| 404 | 资源或路径不存在 | 否 |
| 429 | 超过 QPS 或日配额 | 是,指数退避 |
| 500 / 502 / 503 | 服务端错误或暂时不可用 | 是,有限次重试 |
业务错误码
| code | 含义 | 处理建议 |
|---|---|---|
| 0 | 成功 | 正常解析 data |
| 40001 | 证券代码格式错误 | 使用 代码.交易所 格式 |
| 40002 | 参数缺失或越界 | 检查日期、周期与分页参数 |
| 40003 | 不支持的数据域或周期 | 核对接口文档与授权范围 |
| 40101 | 密钥无效或过期 | 更换密钥 |
| 40301 | 无该证券或数据域权限 | 联系支持调整授权 |
| 42901 | 超过 QPS | 降低并发并按退避重试 |
| 42902 | 超过日配额 | 次日恢复或申请更高配额 |
| 50001 | 服务端内部错误 | 携带 request_id 联系支持 |
限流规则
默认限流为 20 QPS,具体以接入方案为准。限流按密钥与服务维度统计,超限返回 HTTP 429。推送连接数与订阅代码数另有约束,不占用 REST QPS。
- 批量查询优先于逐条查询,减少请求数。
- 历史数据按交易日缓存,避免重复拉取。
- 实时数据使用推送,不要高频轮询。
- 为批量任务设置并发上限,避免瞬时打满配额。
重试策略
建议只对 429 与 5xx 重试,使用指数退避与随机抖动。重试次数不宜无限,超过上限应记录并告警。
text
attempt 1 wait 1s
attempt 2 wait 2s + jitter
attempt 3 wait 4s + jitter
attempt 4 wait 8s + jitter
give up record request_id and alert
幂等性
查询接口天然幂等,可以安全重试;如果未来使用带副作用的接口,必须结合幂等键,避免重复提交。
排查与支持
联系支持时请提供:request_id、请求时间、证券代码、接口路径、HTTP 状态与业务 code。不要发送完整 API Key;如需确认密钥身份,可提供密钥后四位。
支持邮箱:support@ftlib.com。