错误处理

适用场景

请求失败、任务超时、返回字段和预期不一致时，优先检查这里。

核心规则

先保留请求时间、路径、HTTP 状态码、脱敏后的请求体和响应体
异步生图请额外记录任务 id、轮询路径，以及 Retry-After / next_poll_after_ms
视频任务请额外记录 id、task_id 或 video_id
若使用代理、跳过证书校验或公司网关，也要一并记录

常见问题

401 / 403

API Key 无效
Header 名称或格式错误
渠道和密钥不匹配

400

JSON 结构错误
多模态内容数组格式错误
图片字段数量超出限制
异步生图未开启 output=url
引用了非公网 http/https 图片 URL

异步生图 409

GET /v1/tasks/{id}/content 调用过早
任务仍处于 accepted、queued 或 running

异步生图 429

同一个任务轮询过快
同一个 batch 轮询过快
未按 Retry-After 或 next_poll_after_ms 指示做退避重试

异步生图 503

本地任务队列已满
可以稍后重试提交，或先检查网关容量配置

异步任务 `upstream_timeout`

任务通常已经成功创建，失败发生在上游执行阶段
先检查输入图片 URL 是否稳定可访问
再检查提示词、参考图数量和任务复杂度是否过高
结合业务幂等策略决定重试，避免对同一素材做高频重复提交

异步链路层 `SSL_ERROR_SYSCALL`

在高频并发轮询或高并发提交时，可能出现 curl (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL
这更像 TLS / 连接层抖动，不等于任务已经在业务层失败
若任务已经拿到 id，优先继续按任务 ID 重试轮询，而不是立即判定整笔任务失败
若提交阶段直接出现该错误且没有拿到 id，按幂等策略重新提交

404

使用了错误的接口路径
模型名拼写不正确
对已过期任务 ID 发起轮询

视频任务长时间处理中

输入图片 URL 外网不可达
轮询策略过于激进
任务本身耗时较长，未设置足够超时时间

排查清单

确认 Base URL 和接口路径完全正确
确认 Authorization 头存在且格式正确
检查图片 URL 是否公网可访问
检查模型名、尺寸、时长等枚举值是否合法
异步生图确认请求里最终生效的是 output=url
异步生图轮询 GET /v1/tasks/{id} 或 POST /v1/tasks/batch-get 时遵守 Retry-After / next_poll_after_ms
视频任务请轮询 GET /v1/videos/{id} 并保留完整状态字段
若任务进入 failed/upstream_timeout，请同时记录输入资源 URL 与任务创建时间，便于判断是否为上游超时

下一步

更完整的联调资料见排查建议。