跳到主要内容

开发者说明

错误模型（Error Model）

先确认自己真的走正式接口，再拿 Bearer、发第一条请求、处理同步或异步结果。

适合谁已经决定做直接接口接入的开发团队
解决动作理解 Bearer、请求对象和结果处理链路
下一步进入首次请求、接口参考和上线准备
适合场景团队已经决定做直接接口接入
不适合业务方选择接入模式时阅读
第一条请求API 参考
步骤 01获取凭证
步骤 02发送请求
步骤 03处理结果
开发路径
01选择路径02首次请求03鉴权与对象04接口参考
受控开放

Base URL 与白名单端点可验证；API Key 与生产权限仍通过开通流程发放。本文档用于集成预览，不等价于匿名自助开放。

这页不试图罗列“所有错误码”，而是给你一个更可落地的排查框架：把错误分成三段处理，让日志、告警、重试和客服话术保持一致。

  1. 请求前：鉴权 / 权限

    凭证、scope、entitlement 或 quota 被拒绝。

    优先动作优先修正凭证或正式权限配置；不要盲目重试。查看详细排查

  2. 请求内：请求体校验

    缺少字段或格式不符合当前 OpenAPI。

    优先动作对照 schema 修复 payload 后再发起请求。查看详细排查

  3. 请求后：后续查询 / 流式读取

    异步 workflow 已受理，但后续 URL 不可用或过期。

    优先动作只沿响应返回的 URL 处理，绝不自行推断路由。查看详细排查

1) 鉴权与 Scopes​

  • Bearer 凭证无效
  • 缺少必要 scope
  • 组织 entitlement 不满足
  • quota 已耗尽

特点：这类问题不会进入执行阶段；优先检查 Bearer、scope、组织权限与配额。

2) 请求体校验​

  • schema 格式不正确
  • text 与 structured_input 同时缺失

特点：你的请求体没有满足 OpenAPI 定义的最小结构；优先对照请求 schema，并在日志中打出 request_id / trace_id（如果已返回）。

如果集成方把中性的协议对象放进 structured_input，嵌套内容的校验错误可能会提到 raw_input 或 structured_summary；这不代表它们变成了 POST /api/execute 顶层 HTTP 契约字段。

3) 后续查询与异步执行​

  • workflow 不存在
  • workflow 已无法查询

特点：只在异步或流式读取时出现；不要“猜 URL”，只沿响应返回的 follow-up URL 继续请求。

推荐阅读

相关页面

错误处理通常与鉴权、生命周期与 API 字段同时关联。

鉴权与 Scopes

Bearer、required_scopes 与常见拒绝原因。

执行生命周期

同步/异步差异、follow-up URL 的用法。

API Reference

字段与响应结构对照。

生产准备

幂等、重试、回调与上线检查。