云 API
错误与速率限制
zn 云端 API 的错误格式、状态码和速率限制响应头。
错误以 JSON 返回，包含 error 消息。配额错误还会附带机器可读的 code。
{"error": "Invalid API key"}{"error": "Monthly call limit reached", "code": "MONTHLY_LIMIT_REACHED"}状态码
| 状态码 | 含义 | 处理方式 |
|---|---|---|
| 400 | 请求体缺少 input，或 input 超过 20,000 个字符 |
发送 {"input": "..."}，并拆分过长的输入 |
| 401 | API 密钥缺失或无效 | 检查 Authorization 请求头以及仪表盘中的密钥 |
| 429 | 已达到月度上限（MONTHLY_LIMIT_REACHED） |
按 Retry-After 等待，购买额度包或升级套餐 |
| 500 | 分析意外失败 | 稍等后重试一次（每次请求都计入额度） |
请根据 HTTP 状态码和 code 分支处理，不要依赖 error 的文本，它可能会变化。
速率限制响应头
成功响应以及 401 和 429 响应会返回 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset，方便你在触发 429 之前主动降速。429 响应还会包含 Retry-After。
失败时放行还是拒绝？
请明确 zn 不可达时智能体的行为。对于高影响工具（shell、支付、数据删除），应失败即拒绝（fail closed）：不要运行该工具。对于低影响的读取操作，可以失败即放行（fail open），并保留本地 zn-gate 规则作为兜底。