错误处理与限制

常见错误响应

鉴权或限流失败由网关或中间件提前返回：

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authorization Bearer or Key token is required"
  },
  "request_id": "..."
}

限流示例：

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded, please try again later"
  },
  "request_id": "..."
}

模型标识不存在：

{
  "detail": "App not found: not_exists"
}

模型未授权：

{
  "detail": "Model not allowed for this user"
}

webhook 不支持：

{
  "detail": "webhook not supported"
}

运行时失败：

{
  "detail": "Runtime execution failed"
}

不支持的能力

Webhook

当前不支持 webhook。请求体、查询参数或请求头中携带 webhook 回调信息会被拒绝：

curl -X POST "${BASE_URL}/v1/queue/${ENDPOINT}" \
  "${COMMON_HEADERS[@]}" \
  -d '{
    "prompt": "a cinematic photo of a cat astronaut",
    "webhook_url": "https://example.com/hook"
  }'

400

{
  "detail": "webhook not supported"
}

警告

当前版本不提供回调投递能力，请使用 status_url 轮询任务状态。

SSE stream

curl "${BASE_URL}/v1/queue/${ENDPOINT}/requests/${REQUEST_ID}/status/stream" ...

404

{
  "detail": "SSE streaming not supported"
}

Sync

当前多模态 queue 只提供异步任务协议，不提供同步生成入口。

curl -X POST "${BASE_URL}/v1/queue/${ENDPOINT}/sync" ...

404

{
  "detail": "Not Found"
}

处理建议

• 创建任务成功后保存 request_id，后续轮询状态、获取结果和取消任务都需要使用它。
• 轮询时只根据 status 判断是否终态；COMPLETED 后再检查 error 字段判断成功或失败。
• response_url 未完成时可能返回 HTTP 202，不要当作异常任务。
• 对 404 Request not found 不要重试太久，通常表示 request_id 错误、endpoint 不匹配或无权限。
• 对 5xx / 502 可做有限重试；不要无限重试创建任务请求，避免重复创建任务。