错误码说明

本文详细介绍 API 返回的错误码及其处理方式。

错误响应格式

{
  "code": 400,
  "message": "参数校验失败",
  "errors": [
    { "field": "idCard", "message": "身份证号格式不正确" }
  ],
  "requestId": "req_abc123",
  "timestamp": "2024-01-01T00:00:00Z"
}

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	认证失败
403	无权限访问
404	资源不存在
429	请求过于频繁
500	服务器内部错误

业务错误码

通用错误 (1xxxx)

错误码	说明	解决方案
10001	参数缺失	检查必填参数
10002	参数格式错误	检查参数格式
10003	参数值无效	检查参数取值范围

认证错误 (2xxxx)

错误码	说明	解决方案
20001	API Key 无效	检查 API Key
20002	API Key 已过期	重新生成密钥
20003	权限不足	联系管理员开通

业务错误 (3xxxx)

错误码	说明	解决方案
30001	查询无结果	正常情况，无匹配数据
30002	数据源暂不可用	稍后重试
30003	额度不足	充值或升级套餐

错误处理示例

try {
  const response = await api.query(params);
} catch (error) {
  switch (error.code) {
    case 20001:
      // 重新获取 API Key
      break;
    case 30003:
      // 提示用户充值
      break;
    default:
      // 通用错误处理
  }
}