> ## Documentation Index
> Fetch the complete documentation index at: https://steadyrenew.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误和限流

> 开放 API 的错误响应、requestId、rate limit headers 和 CORS 行为。

# 错误和限流

错误响应使用稳定 JSON 结构：

```json theme={null}
{
  "error": {
    "code": "invalid_subscription",
    "message": "Invalid option",
    "field": "period",
    "suggestedFix": "Use one of the supported billing periods: monthly, yearly, custom.",
    "allowedValues": ["monthly", "yearly", "custom"]
  },
  "requestId": "request-..."
}
```

当服务端能定位具体修复方式时，会返回 `field`、`suggestedFix`、`allowedValues` 或 `writableFields`。AI Agent 应优先使用这些字段修正请求，而不是自行猜测。

## 常见错误码

| 状态码 | Code | 说明 |
| -: | - | - |
| `400` | `invalid_json` | 请求体不是合法 JSON 对象 |
| `400` | `invalid_subscription` | 订阅字段未通过校验 |
| `400` | `invalid_subscription_field` | 请求尝试写入服务端管理字段 |
| `400` | `invalid_subscription_id` | 订阅 ID 不是合法 UUID |
| `400` | `invalid_pagination` | `limit` 或 `offset` 查询参数超出范围 |
| `400` | `invalid_query` | 过滤或 `sort` 查询参数非法 |
| `400` | `empty_patch` | PATCH 请求体没有包含任何可写字段 |
| `401` | `authentication_required` | 缺少 Bearer token |
| `401` | `invalid_api_key` | API Key 无效或已撤销 |
| `403` | `insufficient_scope` | API Key 缺少该操作所需的 `write` 权限 |
| `404` | `subscription_not_found` | 当前 API Key owner 下不存在该订阅 |
| `405` | `method_not_allowed` | HTTP method 不支持 |
| `429` | `rate_limit_exceeded` | 用户请求限额或无效认证限额已耗尽 |
| `500` | `internal_error` | 未预期的服务端错误 |

## 恢复字段

| 字段 | 含义 |
| - | - |
| `field` | 导致错误的请求字段 |
| `suggestedFix` | 人和 AI 都能读懂的修正建议 |
| `allowedValues` | `currency` 或 `period` 等枚举字段的合法值 |
| `writableFields` | 订阅 `POST` 和 `PATCH` 请求接受的可写字段 |

不可写字段示例：

```json theme={null}
{
  "error": {
    "code": "invalid_subscription_field",
    "message": "Field is not writable: id",
    "field": "id",
    "suggestedFix": "Remove server-managed fields such as id, createdAt, and updatedAt before retrying.",
    "writableFields": [
      "amount",
      "category",
      "currency",
      "customDate",
      "billingAnchorDay",
      "lastPaymentDate",
      "nextPaymentDate",
      "name",
      "notificationEnabled",
      "period"
    ]
  },
  "requestId": "request-..."
}
```

## 权限范围（Scopes）

API Key 带有 scopes。`read` Key 可以查询、读取订阅与通知设置，并调用分析与审计端点；`write` Key 额外允许创建、更新、删除，以及更新通知设置。用只读 Key 执行写操作会返回 `403 insufficient_scope`，此时不要重试——需要换用带 `write` 权限的 Key。详见 [API 认证](/docs/zh-CN/api/authentication#权限范围-scopes)。

## Rate limit headers

认证成功后的响应会包含：

```text theme={null}
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
```

`X-RateLimit-Reset` 是 Unix 秒级时间戳，表示当前固定窗口何时重置。

校验失败（`400`）会在扣减每小时限额之前被拒绝，因此不计入限额，也不带 rate limit headers。修正请求体后重试是「免费」的。

`429` 响应还会带 `Retry-After` header，表示需要等待多少秒后再重试。它同时适用于「用户请求限额」和「无效 API Key 尝试过多」两种封锁。

```text theme={null}
Retry-After: 2700
```

## CORS

订阅 API 支持浏览器预检请求：

```text theme={null}
OPTIONS /api/v1/subscriptions
OPTIONS /api/v1/subscriptions/{id}
```

允许的方法：

```text theme={null}
GET, POST, PATCH, DELETE, OPTIONS
```

允许的 headers：

```text theme={null}
Authorization, Content-Type
```

不要把 API Key 暴露在不可信浏览器环境里。CORS 主要用于开发者工具、内部面板或可信本地工作流。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.