# 错误码、限制与重试 先记录 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 大小计算，包含转义与裁剪提示；[受保护内容的例外](/docs/reference/tools/)仍适用。单次输出容量由模型渠道决定。运行不设累计 Token、每日 Token/模型调用、步骤数、工具总次数、总时长和每轮美元预算；旧累计配额字段兼容接收但忽略。实际准入仍检查余额、模型能力、权限和并发容量。某些错误的 HTTP 状态依发生阶段不同：创建请求的 4xx/5xx、已接受 Run 的最终 `error.code` 与诊断都要看。[运行参考](/docs/reference/runtime/)。 旧记录可能保留 `TOKEN_BUDGET_EXCEEDED`、`DAILY_QUOTA_EXCEEDED`、`STEP_BUDGET_EXCEEDED`、`TOOL_BUDGET_EXCEEDED`、`COST_BUDGET_EXCEEDED` 或 `RUN_TIMEOUT`；新运行策略不再产生这些配额错误。已终结的旧 Run 不会自动重启。 GET 与快照恢复可在同一身份范围内重查。POST 响应未知时，仅当原正文/参数/幂等键都保存且协议支持幂等时按原请求重试；已知业务副作用先查产品记录。认证失败、权限不足、费用未知或已进入终态，都不是换键再次启动的理由。[恢复决策](/docs/integration/recovery/)。