错误处理
TurningAPI 使用标准的 HTTP 状态码来表示请求的结果。本页面列出了所有可能的错误码及其处理方法。
错误响应格式
当请求失败时，API 会返回以下格式的 JSON 响应：
JSON
{
"code": 40001,
"message": "Invalid API Key",
"request_id": "req_abc123xyz",
"details": {
"suggestion": "请检查您的 API Key 是否正确"
}
}HTTP 状态码
| 状态码 | 名称 | 描述 |
|---|---|---|
| 200 | OK | 请求成功 |
| 400 | Bad Request | 请求参数错误或格式不正确 |
| 401 | Unauthorized | API Key 无效或已过期 |
| 403 | Forbidden | 没有权限访问此资源 |
| 404 | Not Found | 请求的资源不存在 |
| 429 | Too Many Requests | 请求频率超出限制 |
| 500 | Internal Server Error | 服务器内部错误 |
| 502 | Bad Gateway | 网关错误 |
| 503 | Service Unavailable | 服务暂时不可用 |
业务错误码
除了 HTTP 状态码，API 还会在响应体中返回更详细的业务错误码：
| 错误码 | 描述 | 解决方案 |
|---|---|---|
40001 | API Key 无效 | 检查 API Key 是否正确，是否已过期 |
40002 | 缺少必填参数 | 检查请求体是否包含所有必填字段 |
40003 | 参数格式错误 | 检查参数类型和格式是否符合文档要求 |
40004 | 查询目标不存在 | 确认查询的企业或个人信息是否正确 |
40301 | 余额不足 | 请充值后重试 |
40302 | 权限不足 | 请升级套餐或联系客服开通权限 |
42901 | 请求频率过高 | 降低请求频率，使用指数退避重试 |
错误处理建议
实现重试机制
对于 5xx 错误和 429 错误，建议实现指数退避重试策略。初始等待 1 秒，最大重试 3 次。
记录 request_id
每个响应都包含 request_id，在联系技术支持时请提供此 ID 以便快速定位问题。
优雅降级
在生产环境中，建议实现优雅降级策略，当 API 不可用时提供备选方案。