跳转至

错误码与限流

统一错误格式

所有接口错误返回统一 Envelope：

1
2
3
4
5
6
{
  "request_id": "req_01J5KS72E3VP6A8C0R9Z4W1XTD",
  "code": 40102,
  "message": "Invalid API key",
  "data": null
}
  • code 是业务错误码，程序应以其为判断依据。
  • message 用于人工阅读，不应作为程序判断依据。
  • request_id 用于问题反馈与日志追踪。

错误码表

HTTP code 含义 建议处理
400/422 40001 参数、字段、必填 Header 或日期格式错误 修正请求，不要原样重试
422 40002 Excel 工作簿校验或重算失败 根据错误行和原因修正后重新导入
401 40101 缺少后台会话或要求的认证信息 登录后台或补齐认证信息
401 40102 用户名密码、Session 或 API Key 无效 检查凭据，重新登录或创建 Key
401 40103 Session 或 API Key 已过期 重新登录或创建新 Key
403 40301 角色/Origin 不允许，或 Key、用户、IP、scope 被拒绝 检查会话角色和访问策略
403 40302 无该指数的数据权限 联系管理员授权指数范围
404 40401 资源不存在 检查路径与资源标识
409 40901 用户名重复、订单冲突或系统已初始化 修改用户名或进入正常流程
429 42901 登录尝试或 API Key 分钟频率超限 下一自然分钟后退避重试
429 42902 每日额度已用完 次日重试或调整额度
500 50000 内部错误 保存 request_id 后联系维护人员

数据接口鉴权链路

POST /api/v1/query 的每次请求依次检查（任一失败即返回对应错误）：

  1. Key 格式与哈希是否正确 → 40102
  2. Key 是否 active、是否删除/过期 → 40102 / 40103 / 40301
  3. 所属用户是否 active、是否允许 API 访问 → 40301
  4. 客户端 IP 是否满足白名单 → 40301
  5. 是否包含所需 scope → 40301
  6. 请求中的指数是否在允许范围内 → 40302
  7. 服务端频率保护与每日额度 → 42901 / 42902
  8. 会员指数覆盖 → 无权限时 40301，省略指数条件时自动过滤
  9. 会员时效上限（数据日期过滤）→ 静默过滤，返回空结果而非报错

不带 X-API-Key 时按网站身份查询，不走上面的 Key 校验。带了 Key 但格式错误、哈希不匹配或已失效，返回 40102 或 40103，不会退回网站身份。

限流与额度

新建 Key 的额度由账号权益决定；服务端同时执行分钟级频率保护，实际生效值取 「Key 上记录的额度」与「当前账号权益额度」中的较小者，以 Key 元数据和部署配置为准。

维度 免费用户 专业会员 说明
单 Key 调用频率 10 次/分钟 10000 次/分钟 分钟级频率保护，超限 42901
单 Key 每日额度 10 次/日 10000 次/日 Key 级，按 UTC 自然日统计已认证调用
单次行数 5000 行 5000 行 limit 超过上限会被压低到服务端配置值
Key 数量 1 个 不限 由账号权益决定

上表为默认值，超级管理员可在 等级与权益 中调整。 实际生效值取「Key 上记录的额度」与「当前账号权益额度」中的较小者，并以响应与 Key 元数据为准。

规则：

  • 只有通过前置校验（识别出 Key 并通过鉴权）的调用才计入额度与调用日志；无效 Key 的失败尝试不计数。
  • 触发分钟级频率保护返回 429 / 42901；每日额度用尽返回 429 / 42902。
  • 客户端应等待下一分钟或下一个 UTC 自然日，并使用带随机抖动的指数退避重试，不要无间隔重试。
  • 不带 API Key 的网站查询不计入 Key 额度。GET /api/v1/config 与 GET /api/v1/membership 也不是行情查询，不计入额度。

客户端重试建议

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import random
import time

def query_with_retry(session, url, payload, max_retries=5):
    for attempt in range(max_retries + 1):
        response = session.post(url, json=payload, timeout=30)
        if response.status_code != 429:
            return response
        if attempt == max_retries:
            raise RuntimeError("rate limit persists")
        # 指数退避 + 随机抖动：1s, 2s, 4s, 8s, 16s
        delay = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(delay)

时效过滤说明

会员时效上限通过静默过滤生效（见 数据时效规则）：

  • index_daily / index_quote 中超出上限的日期不会返回，也不会报错。
  • 指定 trade_date 为延迟线之后的日期 → 返回空 items，code: 0。
  • index_basic 与 trade_calendar 不受影响。