错误和限流
错误响应使用稳定 JSON 结构:field、suggestedFix、allowedValues 或 writableFields。AI Agent 应优先使用这些字段修正请求,而不是自行猜测。
常见错误码
恢复字段
/api/v1/subscriptions 不可写字段错误示例:
权限范围与套餐限制
- Scopes:
readKey 可以查询、读取订阅与通知设置,并调用分析与审计端点;writeKey 额外允许创建、更新、删除订阅以及更新通知设置。用只读 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请求头,指示重试前需等待的秒数: