FTLib
版本 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 状态码

常见 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。