主题
响应格式与错误码
统一响应结构
多数接口返回 JSON,外层字段固定:
json
{
"success": true,
"code": 200,
"message": "获取成功",
"data": {},
"timestamp": 1790345000
}| 字段 | 类型 | 说明 |
|---|---|---|
success | bool | 业务是否成功 |
code | int | 业务状态码,200 为成功;与 HTTP 状态码不是一回事 |
message | string | 结果提示 |
data | object / array | 业务数据,不同接口结构不同 |
timestamp | int | 服务端 Unix 时间戳(秒) |
例外情况
图片生成、音乐播放、文件下载类接口可能直接返回二进制资源、纯文本,或 302 跳转到实际资源地址。前端代码里不要无条件读取 res.data。
判断成功的正确顺序
- 先看 HTTP 状态:非 2xx 按网络/网关错误处理。
- 再解析 JSON 并判断
code === 200。 - 失败时把
code和message一起记进日志。
js
const res = await fetch(url).then(r => r.json())
if (res.code !== 200) {
console.error(res.code, res.message)
return
}通用错误码
| code | msg | 说明 |
|---|---|---|
| 400 | 参数错误 | 缺少必要参数或参数格式不正确 |
| 401 | Invalid API key | Key 无效或不存在 |
| 402 | 账号余额不足 | 余额不足以支付本次调用 |
| 403 | API key required | 该接口要求 Key |
| 404 | API not found | 接口标识不存在 |
| 410 | API removed | 接口已永久下架 |
| 429 | 请求过于频繁 | 超过限流阈值 |
| 500 | 服务器内部错误 | 服务端异常 |
| 502 | 上游接口不可用 | 第三方数据源不可用且无缓存 |
| 503 | API is under maintenance | 维护中或暂时不可用 |
常见失败原因
- 400:必填参数没传,或取值格式不对。
- 401 / 403:Key 问题,见 鉴权与 API Key。
- 404:路径写错或接口已移除。
- 429:触发限流,见 限流与配额。
- 502:第三方数据源暂时不可用,稍后重试。