错误码与排查

公共失败响应只包含 code、message、requestId、可选的 messageId 和 retryable。业务判断以 code 和 retryable 为准，requestId 用于管理后台检索；内部处理阶段和技术详情不会通过公开接口返回。

json

{
  "code": 40004,
  "message": "Unsupported language.",
  "requestId": "req_example",
  "messageId": "out_20260722_001",
  "retryable": false
}

错误码	现象	常见原因	处理方式	可自动重试
`40001`	请求被拒绝	必填字段缺失、长度或格式不符	对照接口字段修正请求	否
`40002`	图片无法处理	非 HTTPS、地址过长或无法公开访问	换成稳定可下载的 HTTPS 地址	否
`40003`	主动场景不支持	`scenario` 不在支持列表	使用文档列出的场景	否
`40004`	语言不支持	`language` 值错误	使用 `zh-CN`、`zh-TW` 或 `en-US`	否
`40005`	语气不支持	`tone` 值错误	使用支持的语气值	否
`40006`	上下文无效	事实过多、过长、不安全，或提醒缺少事实	清理 `context.facts` 后重试	否
`40007`	回复长度不支持	`responseLength` 值错误	使用 `short`、`medium` 或 `long`	否
`40101`	鉴权失败	密钥缺失、错误或已撤销	检查 Bearer Header，必要时创建新密钥	否
`40201`	无法继续生成	账户余额不足	充值或调整账户额度	否
`40301`	API 已停用	用户或管理员关闭了访问	在开放平台恢复访问	否
`40302`	分身未就绪	分身配置不完整或当前不可用	回到分身页面完成配置	否
`40401`	资源不存在	批次 ID 错误或不属于当前账号	核对 ID 和密钥所属账号	否
`40901`	消息重复	同一 `messageId` 已处理	读取原业务结果，不要换 ID 重发同一消息	否
`40902`	主动消息被跳过	当前场景要求的历史或上下文不足	将其作为 `status: "skipped"` 的 `skipCode` 处理，不要强制发送	否
`40903`	主动消息被跳过	用户在任务执行前已恢复活跃	尊重跳过结果，无需重试	否
`40904`	项目已取消	批量任务取消过程中项目未执行	如仍需触达，创建新的业务任务	否
`42901`	请求过于频繁	超过当前调用频率	按指数退避并降低并发	是
`50001`	分身执行失败	运行时处理异常	保存 `requestId` 后短暂退避重试	以响应为准
`50002`	服务内部错误	服务端未知异常	短暂退避重试；持续出现时反馈 `requestId`	以响应为准
`50301`	分身服务暂不可用	服务启动、重连或负载异常	稍后重试	是
`50302`	图片理解失败	图片下载或识别服务暂时失败	检查图片地址；稳定后重试	以响应为准
`50401`	请求超时	生成时间超过服务上限	使用同一 `messageId` 重试	是

错误码与排查 ​

推荐处理流程 ​

错误码与排查

推荐处理流程