Error Codes

All API responses include the following common fields:

• code: Business status code
• message: Description of the status

Common Error Troubleshooting

Connection and Authentication

TBHK Token Authentication

Rate Limits

For code 5 or HTTP 429, do not retry immediately. Batch requests where possible and use exponential backoff:

import time

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

Market Data Permissions

Parameter Errors

Trading Errors

Subscription and Push Errors

Security Best Practices

Private Key Format and Management

Private key format by SDK

Every SDK recommends an RSA private key in PKCS#8 format. A format mismatch causes signature verification to fail:

Private key storage recommendations

• Store the private key file in a protected directory and restrict it to the current user:
  Bash

  chmod 600 your_private_key.pem

• Never commit private keys or configuration files to a code repository. Add these rules to .gitignore:

  *.pem
  tiger_openapi_config.properties
  tiger_openapi_token.properties

• In production, pass the private key in through an environment variable instead of keeping the file on disk:
  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')

• For stricter security requirements, use a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or Alibaba Cloud KMS.
• Never hard-code private keys or an institutional secret_key in source.
• Rotate key pairs periodically: generate a new pair in Developer Center. A six-month rotation interval is recommended.

Token Management (TBHK License)

TBHK license holders manage an additional token. Tokens are valid for 30 days and must be regenerated after they expire:

• Enable automatic refresh so an expired token does not interrupt service:
  PythonJava

  # Python: refresh the token once a day
  client_config.token_refresh_duration = 24 * 60 * 60

  // Java: enable automatic refresh, every 5 days by default
  clientConfig.isAutoRefreshToken = true;
  // Optional: customize the refresh interval and time of day
  // clientConfig.refreshTokenIntervalDays = 3;
  // clientConfig.refreshTokenTime = "03:00:00";

• Keep tiger_openapi_token.properties in the same directory as the primary configuration file.
• After a successful automatic refresh, the SDK also updates the local token file.

Production Deployment

• Configure an IP whitelist in Developer Center.
• Do not log full requests or responses containing account and position data; disable debug logs in production.
• Keep SSL/TLS enabled. Do not disable certificate verification.
• Alert on repeated signature failures, token expiration, frequent rate limits, and code 4001 disconnections.