错误和限流

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

{
  "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` 请求接受的可写字段

不可写字段示例：

{
  "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",
      "status"
    ]
  },
  "requestId": "request-..."
}

权限范围（Scopes）

API Key 带有 scopes。read Key 可以查询、读取订阅，并调用分析与审计端点；write Key 额外允许创建、更新、取消、暂停、恢复和删除。用只读 Key 执行写操作会返回 403 insufficient_scope，此时不要重试——需要换用带 write 权限的 Key。详见 API 认证。

Rate limit headers

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

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

X-RateLimit-Reset 是 Unix 秒级时间戳，表示当前固定窗口何时重置。校验失败（400）会在扣减每小时限额之前被拒绝，因此不计入限额，也不带 rate limit headers。修正请求体后重试是「免费」的。 429 响应还会带 Retry-After header，表示需要等待多少秒后再重试。它同时适用于「用户请求限额」和「无效 API Key 尝试过多」两种封锁。

Retry-After: 2700

CORS

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

OPTIONS /api/v1/subscriptions
OPTIONS /api/v1/subscriptions/{id}

允许的方法：

GET, POST, PATCH, DELETE, OPTIONS

允许的 headers：

Authorization, Content-Type

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

​错误和限流

​常见错误码

​恢复字段

​权限范围（Scopes）

​Rate limit headers

​CORS