REST API/错误处理

错误处理

了解错误码、HTTP 状态码以及如何处理 API 错误

错误响应格式

发生错误时，API 返回包含 status: false 和非零 error_code 的响应：

错误响应 400 Bad Request

HTTP 状态码

API 使用标准 HTTP 状态码表示错误的大致类别：

200

成功

请求成功，响应体包含所请求的数据

201

已创建

资源创建成功，响应包含新资源数据

401

未授权

鉴权失败，API 密钥 缺失、无效或已过期

403

禁止访问

访问被拒绝，您没有访问该资源的权限，或配额已超限

404

未找到

所请求的资源不存在，请检查接口 URL 和资源 ID

业务错误码

业务错误表示请求参数或数据处理存在问题：

错误码描述
68300004参数无效！
68300005搜索 API 失败！
68300006分析基础访问错误！
68300007请求错误！
68300008服务错误，请稍后重试！
68300010文件不符合上传规范！

平台错误码

平台错误与鉴权、授权和配额管理相关：

错误码描述
67200001API 调用超出平台设置的总限额！
67200002配额超出限制！
67200003访问令牌已过期或鉴权错误！
67200004无权限或 API 套餐配额已超限！
67200005余额不足，调用失败！
67200006该客户端已过期，调用失败！
67200007超出调用限制，调用失败！

错误处理最佳实践

优先检查 status 字段

处理响应数据前始终检查 status 字段，仅在 status 为 true 时访问 data

实现重试逻辑

对于瞬时错误（5xx 状态码、68300008），实现指数退避重试逻辑，每次重试间隔逐渐增加

记录错误详情

同时记录 error_code 和 error_message 以便调试，如有请求 ID 也一并记录

提供用户友好的提示

将技术错误码转换为用户友好的提示信息，不要将原始错误码暴露给终端用户

需要帮助？

如果遇到持续性错误或需要了解错误码的含义，请联系我们的支持团队，并提供错误码、响应头中的 x-correlation-id 和时间戳，以便更快解决问题。