# 响应码

点金 Open API 使用标准 HTTP 状态码指示请求成功或失败。

`2xx` 表示请求成功；`4xx` 表示客户端错误；`5xx` 表示服务端异常（极少发生）。

## 响应结构

所有 API 响应遵循统一的 JSON 结构：

```json
{
  "httpStatusCode": 200,
  "message": "success",
  "data": { },
  "success": true
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `httpStatusCode` | Integer | HTTP 状态码，与响应头一致 |
| `message` | String | 便于阅读的响应描述 |
| `data` | Object | null | 业务数据，结构因接口而异 |
| `success` | Boolean | `true` 表示请求成功，`false` 表示失败 |

## 错误响应属性

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | String | 业务错误码，用于程序化处理 |
| `message` | String | 错误描述信息 |
| `suggestion` | String | 推荐的处理方式 |

### HTTP 状态码参考

- **200** 成功 — 请求正常处理并返回结果

- **302** 临时重定向 — 附件预览接口，重定向到 OSS 预签名下载地址

- **400** 请求参数错误 — 参数校验失败、类型不匹配、请求体缺失或 JSON 格式错误

- **401** 未授权 — 缺少应用标识、API Key 无效或缺失

- **403** 禁止访问 — 应用不存在或已被禁用、无渠道访问权限

- **404** 资源不存在 — 请求路径无匹配 Handler、资源不存在

- **409** 资源冲突 — 资源已存在，重复创建

- **429** 请求过于频繁 — 触发限流，附带 Retry-After 响应头

- **500** 服务器内部错误 — 未捕获异常、业务逻辑内部错误

- **502** 上游服务错误 — 上游服务端返回 5xx 错误

- **503** 服务不可用 — DNS 解析失败、网络超时等