GloopAPI 接入指南
错误处理
处理错误和重试边界。
先区分请求是否被接受，再决定是否重试。端点页面列出实际状态码、错误外壳与代表性错误；不同协议不一定共享同一 JSON 结构，二进制成功响应也可能在失败时返回 JSON。
响应决策
| 信号 | 下一步 |
|---|---|
| 400 / 字段或模型不支持 | 对照端点 schema 与当前能力目录修改输入，不原样循环重试 |
| 401 / 403 | 核对 Key 有效期、账户、IP、模型或工具权限与额度 |
| 402 / 额度不足 | 补充预算或减少新请求范围；已有任务继续恢复原记录 |
| 404 | 核对资源身份、路径与开关，不能据此推断未知提交从未执行 |
| 409 | 区分幂等冲突、任务未准备、报价变化或资源被引用，按具体错误处理 |
| 410 | 原资源已删除或过期，保留账务和幂等证据，不自动另建任务 |
| 429 / 5xx / 网络超时 | 限流退避或服务恢复后核对是否接受；有幂等契约才安全重放 |
已接受与未知
HTTP 202 表示已接受或仍待完成；工具返回 HTTP 200 也可能是失败任务，需读 status。取消接受不等于取消终态。HTTP 200 的流式响应还可能包含错误事件或异常断流。
创建超时、unknown 与 billing_review 保留原键并按异步恢复查询。重试保存与重新生成是不同操作，文件源已过期时保存重试也可能无法恢复。
诊断信息
记录时间、方法、路径、HTTP 状态、错误码、可用的 request_id、任务 ID 与业务请求键。脱敏请求内容，不记录 Key 或签名链接。诊断时以接口返回的错误信息和用量记录为准。
自动重试必须有次数与时间上限。无法证明未接受的收费请求先核查，不将重复提交作为默认恢复策略。
工具稳定错误码
| 机器码 | HTTP | 安全处理 |
|---|---|---|
| invalid_input | 400 | 核对精确 version 和 input_schema，修正新请求输入 |
| invalid_cursor | 400 | 不自行构造游标，刷新首屏取得新的 next_cursor |
| quote_required / budget_required | 400 | 新调用按能力字段补齐报价或费用上限 |
| quote_expired / quote_stale / invalid_quote | 409 | 仅对确认未提交的新调用核对后重新报价；不存在与他人报价均返回 invalid_quote，不暴露所有权 |
| budget_exceeded | 409 | 新调用预算不足，核对 maximum_usd 后明确选择预算 |
| idempotency_conflict | 409 | 同请求键改变了请求，找回原完整请求；不自动换键重发 |
| tool_service_unavailable | 503 | 基础设施失败或能力暂不可用；未知提交仍用原身份、原键和原完整请求恢复 |
未知创建结果优先查询原 run_id；没有 run_id 时用原 Key、原 Idempotency-Key 与原完整创建请求重放，包含原 quote_id 和 max_cost_usd。不能因为报价过期或开关关闭而修改未知提交。只有确认未被接受的新业务操作才可以重新报价或新建请求键。