错误码、限制与重试
先记录 HTTP 状态、稳定错误 code、request_id、Run ID 和原幂等键。消息文本用于人阅读，程序应按 code 分支；不要把请求正文、应用 Key 或工具 grant 写入公共日志。
| 状态 / code 例子 | 常见原因 | 下一步 |
|---|---|---|
401 UNAUTHORIZED |
登录过期，Key 无效、过期或已撤销 | 重新登录或更换有效 Key，核对身份后再读原资源 |
403 FORBIDDEN / AGENT_FORBIDDEN |
scope、Agent 或产品权限不足 | 回到账户/产品 ACL 检查；不要改 Subject 猜测可访问资源 |
402 INSUFFICIENT_BALANCE |
账号可用余额不足以支付保守预留 | 查可用余额与未结预留；本次模型不会发出 |
409 REVISION_CONFLICT |
Agent/工具集已被更新 | 重新读取 revision、核对差异，再提交新修改 |
409 IDEMPOTENCY_CONFLICT |
原请求号配了不同请求体 | 先核对旧请求结果；改变意图才生成新请求号 |
409 RUN_ACTIVE |
同一会话已有活动 Run | 追加到原 Run，或等待其终态 |
503 MODEL_UNPRICED / MODEL_UNAVAILABLE |
价格、渠道、凭证或开放状态未就绪 | 查看模型目录/售价；不要自动换模型重发 |
CONCURRENCY_LIMIT / RUN_QUEUE_FULL |
当前并发或队列有界限制 | 按服务端建议等待并查询原请求，不制造更多副作用 |
TOOL_TIMEOUT / reconciliation_required |
执行器等待超时或业务结果未知 | 产品查询原业务任务与回执，不能重跑写工具 |
CONTEXT_TOKEN_LIMIT / CONTEXT_SUMMARY_UNAVAILABLE |
必要输入过大或没有可安全摘要的早期前缀 | 检查当前输入、工具定义、Agent 上下文上限和模型渠道，不能靠原样重试修复 |
CONTEXT_CHECKPOINT_INVALID / CONTEXT_PROTOCOL_INVALID |
执行检查点或工具回放链不完整 | 保留原 Session/Run ID，交由维护者核对；不从展示历史自行重放业务操作 |
单次输入预算 max_context_tokens 默认 256,000（可设 1,024–1,000,000），每个工具结果的执行裁剪预算 max_result_context_bytes 默认 16,384 字节（16 KiB，可设 1,024–32,768 字节）。字符窗口与回执字节额度已删除；max_context_chars、max_result_bytes、max_result_tokens 属于非法字段，传入会校验失败，不做兼容。工具字节预算按 result 的紧凑 JSON UTF-8 大小计算，包含转义与裁剪提示；受保护内容的例外仍适用。单次输出容量由模型渠道决定。运行不设累计 Token、每日 Token/模型调用、步骤数、工具总次数、总时长和每轮美元预算；旧累计配额字段兼容接收但忽略。实际准入仍检查余额、模型能力、权限和并发容量。某些错误的 HTTP 状态依发生阶段不同：创建请求的 4xx/5xx、已接受 Run 的最终 error.code 与诊断都要看。运行参考。
旧记录可能保留 TOKEN_BUDGET_EXCEEDED、DAILY_QUOTA_EXCEEDED、STEP_BUDGET_EXCEEDED、TOOL_BUDGET_EXCEEDED、COST_BUDGET_EXCEEDED 或 RUN_TIMEOUT；新运行策略不再产生这些配额错误。已终结的旧 Run 不会自动重启。
GET 与快照恢复可在同一身份范围内重查。POST 响应未知时，仅当原正文/参数/幂等键都保存且协议支持幂等时按原请求重试；已知业务副作用先查产品记录。认证失败、权限不足、费用未知或已进入终态，都不是换键再次启动的理由。恢复决策。