错误代码与状态参考
Smart Money API错误代码、HTTP状态码及故障排除步骤的全面指南。快速理解错误响应并解决集成问题。
2xx 成功代码
成功响应表示请求已被成功处理。
| 代码 | 状态 | 含义 |
|---|---|---|
| 200 | OK | 请求成功。响应体包含请求的数据。 |
| 201 | Created | 资源创建成功。响应包含新创建的资源。 |
| 204 | No Content | 请求成功但无内容返回（例如DELETE操作）。 |
200响应示例
JSON
{
"success": true,
"data": {
"total": 42,
"positions": [...],
"pagination": {
"page": 1,
"limit": 50
}
},
"timestamp": "2026-03-21T14:35:22Z"
}
4xx 客户端错误代码
客户端错误表示请求格式错误或无效。请修正请求后重试。
| 代码 | 状态 | 原因 |
|---|---|---|
| 400 | Bad Request | 请求语法错误。检查查询参数、请求头和请求体。 |
| 401 | Unauthorized | 缺少或无效的身份验证凭据。检查API密钥或JWT令牌。 |
| 402 | Payment Required | 订阅付款失败。请在账户中更新账单信息。 |
| 403 | Forbidden | 已认证但无权访问该资源。您的订阅计划不包含此功能。 |
| 404 | Not Found | 资源不存在。检查端点URL和参数。 |
| 429 | Too Many Requests | 超出速率限制。请稍后重试。检查Retry-After头。 |
| 422 | Unprocessable Entity | 验证失败。请求参数无效或缺少必填字段。 |
身份验证错误示例
缺少API密钥 (401)
JSON
{
"success": false,
"error": {
"code": "AUTH_MISSING_KEY",
"message": "未提供身份验证凭据。",
"resolution": "在Authorization头中包含您的API密钥: Authorization: Bearer sk_live_..."
},
"timestamp": "2026-03-21T14:35:22Z"
}
无效API密钥 (401)
JSON
{
"success": false,
"error": {
"code": "AUTH_INVALID_KEY",
"message": "无效或过期的API密钥。",
"resolution": "从您的控制台生成新API密钥: https://smartmoneyapi.com/console"
},
"timestamp": "2026-03-21T14:35:22Z"
}
速率限制 (429)
当超出API配额时，服务器返回429 Too Many Requests。检查响应头获取速率限制信息：
HTTP头
X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600
速率限制错误响应
JSON
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "每日API请求限制(10次)已超出。",
"resolution": "升级至Trader(29美元/月，1,000次/天)或Pro(79美元/月，5,000次/天)套餐。",
"reset_at": "2026-03-22T09:00:00Z"
},
"timestamp": "2026-03-21T14:35:22Z"
}
验证错误 (422)
当请求参数无效或缺少必填字段时会发生验证错误。
JSON
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "请求验证失败。",
"details": [
{
"field": "symbol",
"error": "无效的交易对。预期格式: BTCUSDT"
},
{
"field": "min_position_size",
"error": "必须为正数"
}
],
"resolution": "修正验证错误后重试。"
},
"timestamp": "2026-03-21T14:35:22Z"
}
5xx 服务器错误代码
服务器错误表示我方存在问题。这些是临时性的，通常会快速解决。请实现指数退避重试逻辑。
| 代码 | 状态 | 操作 |
|---|---|---|
| 500 | Internal Error | 意外的服务器错误。使用指数退避重试。 |
| 502 | Bad Gateway | 临时服务中断。几秒后重试。 |
| 503 | Service Unavailable | 维护或临时中断。检查状态页面。在Retry-After间隔后重试。 |
| 504 | Gateway Timeout | 请求耗时过长。服务器可能已处理该请求。检查幂等性。 |
服务器错误示例 (503)
JSON
{
"success": false,
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "因维护服务暂时不可用。",
"resolution": "5分钟后重试。查看状态: https://status.smartmoneyapi.com"
},
"timestamp": "2026-03-21T14:35:22Z"
}
故障排除指南
401 Unauthorized - 无效API密钥
问题: 即使提供了API密钥仍收到401错误。
解决方案:
- 确认API密钥已包含在Authorization头中并带有"Bearer"前缀
- 检查API密钥是否过期或被撤销
- 确保使用正确的密钥（生产、测试或开发环境）
- 如果当前密钥丢失，从控制台生成新API密钥
403 Forbidden - 功能不可用
问题: 在某些端点收到403错误。
解决方案:
- 检查您的API套餐等级。部分端点需要Trader或Pro套餐
- 前往/pricing.html升级套餐以使用高级功能
- 确认API密钥已启用所需权限范围
- 如果您认为应有权访问，请联系支持团队
429 Too Many Requests - 速率限制
问题: 收到429错误并被限制访问。
解决方案:
- 实现指数退避重试逻辑（等待1秒、2秒、4秒等）
- 缓存响应以避免冗余API调用
- 使用WebSocket获取实时数据而非轮询REST端点
- 升级套餐以获得更高配额（Trader 1,000次/天，Pro 5,000次/天）
- 尽可能将多个查询批量处理为单个请求
400 Bad Request - 无效参数
问题: 收到参数格式错误的400错误。
解决方案:
- 查阅API文档了解必选和可选参数
- 验证参数类型（字符串与数字、数组与对象）
- 确保JSON有效且格式正确
- 使用带有正确路径参数的端点URL
- 检查查询参数名称中的拼写错误
5xx服务器错误 - 临时中断
问题： 遇到500、502、503或504错误。
解决方案：
- 检查服务状态：https://status.smartmoneyapi.com
- 实现指数退避的自动重试（最多5-10次尝试）
- 503错误请等待30-60秒后重试
- 使用Retry-After标头确定重试时间
- 订阅状态页面获取事件通知
错误响应格式
所有错误响应均遵循统一格式：
JSON
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "人类可读的错误信息",
"details": {...},
"resolution": "问题解决步骤"
},
"timestamp": "2026-03-21T14:35:22Z"
}