# 通用响应格式

所有 OpenAPI 接口均采用统一 JSON 响应结构。

## 成功响应

```json
{
  "success": true,
  "code": "200",
  "message": "success",
  "data": { "...": "..." },
  "meta": { "...": "..." }
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `success` | boolean | 是否成功 |
| `code` | string | 状态码或业务码 |
| `message` | string | 响应消息 |
| `data` | object / array / null | 响应数据 |
| `meta` | object / null | 分页、统计等元信息 |

## 错误响应

```json
{
  "success": false,
  "code": "ERROR_CODE",
  "message": "Error message",
  "description": "详细错误描述",
  "limit_scope": "app",
  "limit_scope_label": "应用",
  "retry_after_seconds": 300
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `success` | boolean | 固定为 `false` |
| `code` | string | 错误码 |
| `message` | string | 错误消息 |
| `description` | string | 面向用户或开发者的中文说明 |
| `limit_scope` | string / undefined | 限制类错误的对象，可能为 `app` 或 `user` |
| `limit_scope_label` | string / undefined | 限制对象中文说明 |
| `retry_after_seconds` | integer / undefined | 建议等待秒数 |

## 业务错误码

| 错误码 | HTTP 状态码 | 说明 |
|---|---|---|
| `400` | 400 | 请求参数错误 |
| `401` | 401 | 未授权 |
| `403` | 403 | 无权访问 |
| `404` | 404 | 资源不存在 |
| `500` | 500 | 服务内部错误 |
| `INSUFFICIENT_POINTS` | 402 | 积分不足 |
| `VIP_REQUIRED` | 403 | 需要 Premium |
| `SCOPE_NOT_ALLOWED` | 403 | 应用 scope 不足 |
| `USER_SCOPE_NOT_ALLOWED` | 403 | 用户授权 scope 不足 |
| `OPENAPI_USER_REQUIRED` | 403 | 缺少用户身份 |
| `RATE_LIMIT_EXCEEDED` | 429 | 请求触发限制，应按 `Retry-After` 退避 |