Skip to content

响应格式与错误码 ​

统一响应结构 ​

多数接口返回 JSON,外层字段固定:

json
{
  "success": true,
  "code": 200,
  "message": "获取成功",
  "data": {},
  "timestamp": 1790345000
}
字段类型说明
successbool业务是否成功
codeint业务状态码,200 为成功;与 HTTP 状态码不是一回事
messagestring结果提示
dataobject / array业务数据,不同接口结构不同
timestampint服务端 Unix 时间戳(秒)

例外情况

图片生成、音乐播放、文件下载类接口可能直接返回二进制资源、纯文本,或 302 跳转到实际资源地址。前端代码里不要无条件读取 res.data。

判断成功的正确顺序 ​

  1. 先看 HTTP 状态:非 2xx 按网络/网关错误处理。
  2. 再解析 JSON 并判断 code === 200。
  3. 失败时把 code 和 message 一起记进日志。
js
const res = await fetch(url).then(r => r.json())
if (res.code !== 200) {
  console.error(res.code, res.message)
  return
}

通用错误码 ​

codemsg说明
400参数错误缺少必要参数或参数格式不正确
401Invalid API keyKey 无效或不存在
402账号余额不足余额不足以支付本次调用
403API key required该接口要求 Key
404API not found接口标识不存在
410API removed接口已永久下架
429请求过于频繁超过限流阈值
500服务器内部错误服务端异常
502上游接口不可用第三方数据源不可用且无缓存
503API is under maintenance维护中或暂时不可用

常见失败原因 ​

  • 400:必填参数没传,或取值格式不对。
  • 401 / 403:Key 问题,见 鉴权与 API Key。
  • 404:路径写错或接口已移除。
  • 429:触发限流,见 限流与配额。
  • 502:第三方数据源暂时不可用,稍后重试。

接口数据实时读取自站点数据库