跳转到主要内容
本页面描述了 TickDB 如何在 REST 和 WebSocket API 中报告错误。 它解释了错误格式、常见状态码以及如何正确处理它们。 有关特定端点的错误详情，请参阅按端点分类的错误代码。

​
REST API 错误格式

REST API 错误返回 HTTP 状态码和 JSON 响应体。

​
示例：身份验证错误 (401)

{
  "success": false,
  "error": "Invalid or inactive API key",
  "code": 401
}

​
示例：速率限制错误 (429)

速率限制响应可能包含额外字段以帮助客户端恢复或升级。 
{
  "success": false,
  "error": "Rate limit exceeded",
  "code": 429,
  "limit": 60,
  "used": 60,
  "reset_at": 1700000000,
  "plan": "free",
  "upgrade_to": "standard"
}

​
WebSocket 错误格式

WebSocket 错误分为两类：
  1. 连接级错误（HTTP 状态码如 401、403、429）
  2. 消息级错误（自定义错误代码）

​
示例：消息级错误

{
  "cmd": "subscribe",
  "code": 2001,
  "message": "symbols parameter is required"
}

​
常见 HTTP 状态码

HTTP 状态描述典型原因
200成功请求成功
400错误请求缺少或无效的参数
401未授权缺少、无效或已停用的 API 密钥
403禁止访问此端点或市场的权限被拒绝
404未找到端点或交易品种未找到
429请求过多超出速率限制
500内部服务器错误意外的服务器错误
502网关错误上游服务错误
503服务不可用临时服务中断

​
常见 WebSocket 错误代码

WebSocket 错误代码是自定义代码，不是 HTTP 状态码。
代码描述典型原因
2001无效的消息格式或命令JSON 格式错误、未知命令或缺少字段
2003深度订阅不可用深度频道暂时禁用
2004交易订阅不可用交易频道暂时禁用

​
错误处理最佳实践

  • 在解析响应之前始终检查 HTTP 状态码。
  • 对于 429 错误，在 reset_at 之前等待后再重试。
  • 不要立即重试 500 错误；使用指数退避。
  • 在本地验证请求参数以避免 400 错误。
  • 对于 WebSocket API：
    • 确保消息是有效的 JSON
    • 始终包含必需字段（cmd、channel、symbols）

​
相关文档

  • 身份验证 – API 密钥使用和权限
  • 数据规范 – 交易品种格式和市场定义
  • 按端点分类的错误代码 – 每个 API 端点的详细错误消息