跳转到主要内容

错误和限流

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

常见错误码

恢复字段

/api/v1/subscriptions 不可写字段错误示例:

权限范围与套餐限制

  • Scopes:read Key 可以查询、读取订阅与通知设置,并调用分析与审计端点;write Key 额外允许创建、更新、删除订阅以及更新通知设置。用只读 Key 执行写操作会返回 403 insufficient_scope,此时不要重试——需要换用带 write 权限的 Key。详见 API 认证。
  • 高级版分析:/api/v1/analytics/duplicates 与 /api/v1/analytics/optimizations 在 Free 账户上返回 403 premium_required;/api/v1/analytics/summary 在所有套餐下均可用。

Rate limit headers

认证成功后的 /api/v1/* 响应会包含:
  • 默认已认证配额:Free 与 Premium 账户均为每账户每分钟 60 次请求(API_RATE_LIMIT_PER_MINUTE)。
  • X-RateLimit-Reset 是 Unix 秒级时间戳,表示当前 1 分钟固定窗口何时重置。
  • POST、PATCH 请求体和查询参数的校验失败(400)会在扣减每分钟限额之前被拒绝,因此不消耗配额,也不携带 rate limit headers。修正请求体后重试不占额度。
  • 所有 429 rate_limit_exceeded 响应(无论是每分钟用户请求限流还是每小时无效 Key 尝试封锁)都会附带 Retry-After 请求头,指示重试前需等待的秒数:

CORS

开放 API 支持浏览器预检请求:
不要把 API Key 暴露在不可信的公开浏览器环境中。CORS 主要用于开发者工具、内部面板或受信任的本地工作流。