错误代码

所有 API 请求均返回以下公共参数，用于描述请求结果：

• code：业务状态码
• message：状态描述

常见错误排查指南

连接与认证

Token 认证（TBHK 牌照）

频率限制

💡

频率限制恢复建议

收到 HTTP 429 后，请不要立即重试。推荐使用指数退避策略：

Python

import time
for attempt in range(3):
    try:
        result = quote_client.get_stock_briefs(['AAPL'])
        break
    except Exception as e:
        if 'rate limit' in str(e).lower():
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
        else:
            raise

行情权限

参数错误

交易错误

订阅推送错误

安全最佳实践

私钥格式与管理

私钥格式对照

不同 SDK 需要使用不同格式的 RSA 私钥，格式不匹配会导致签名验证失败：

⚠️

如果遇到 failed to verify signature 错误，请首先确认私钥格式与所用 SDK 匹配。在开发者页面生成密钥时，两种格式的私钥均会提供，请下载对应格式。

私钥存储建议

• 将私钥文件存放在安全目录中，设置文件权限为仅当前用户可读：
  Bash

  chmod 600 /path/to/private_key.pem

• 不要将私钥文件或配置文件提交到代码仓库。建议在 .gitignore 中添加以下规则：

  *.pem
  tiger_openapi_config.properties
  tiger_openapi_token.properties

• 生产环境中，建议通过环境变量传入私钥内容，避免私钥文件直接存放在服务器磁盘上：
  Python

  import os
  client_config = TigerOpenClientConfig()
  client_config.private_key = os.environ.get('TIGER_PRIVATE_KEY')
  client_config.tiger_id = os.environ.get('TIGER_ID')
  client_config.account = os.environ.get('TIGER_ACCOUNT')

• 对于更高安全要求的场景，建议使用密钥管理服务（如 AWS Secrets Manager、HashiCorp Vault、阿里云 KMS）存储和管理私钥
• 定期轮换密钥对：在开发者后台生成新的密钥对。建议至少每 6 个月轮换一次

Token 管理（TBHK 牌照）

TBHK 牌照用户需要额外管理 Token，Token 有效期为 30 天，过期后需重新生成：

• 推荐开启自动刷新，避免 Token 过期导致服务中断：
  PythonJava

  # Python: 每天自动刷新一次 Token
  client_config.token_refresh_duration = 24 * 60 * 60

  // Java: 开启自动刷新，默认每5天刷新一次
  clientConfig.isAutoRefreshToken = true;
  // 可选：自定义刷新间隔和时间
  // clientConfig.refreshTokenIntervalDays = 3;
  // clientConfig.refreshTokenTime = "03:00:00";

• Token 文件 tiger_openapi_token.properties 需与主配置文件放在同一目录下
• 自动刷新成功后 SDK 会同时更新本地的 Token 文件

生产环境部署建议

• IP 白名单：在开发者后台配置 IP 白名单，仅允许生产服务器的 IP 访问 API。多个 IP 之间用 ; 分隔
• 日志安全：避免在日志中打印完整的请求/响应内容，尤其是包含账户信息、持仓数据的内容。建议在生产环境关闭 debug 级别日志：
  PythonJava

  # Python: 设置日志级别为 WARNING 或以上
  import logging
  client_config.log_level = logging.WARNING

  // Java: 关闭 debug 日志
  ApiLogger.setDebugEnabled(false);

• secret_key 保管：机构用户的 secret_key 用于 API 身份认证，切勿在客户端代码中硬编码或提交到代码仓库。建议通过环境变量或密钥管理服务注入
• 网络安全：SDK 默认使用 SSL/TLS 加密传输（Java: clientConfig.isSslSocket = true），请勿关闭此选项
• 异常监控：建议对以下关键事件设置告警监控：
  • 签名验证连续失败（可能密钥泄露后被替换）
  • Token 过期未及时刷新
  • 频率限制（code=5）频繁触发
  • 长连接被踢出（code=4001）