错误处理

统一错误码

先依据 HTTP 状态和稳定的 error.code 决定是否重试，再记录 request_id 用于追踪。

错误响应

{
  "request_id": "req_xxx",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "接口密钥无效"
  }
}

错误码	HTTP	含义	处理建议
`INVALID_API_KEY`	401	Bearer 头或密钥无效	检查服务端配置，不要原样重试
`API_KEY_DISABLED`	401	密钥已禁用或删除	更换有效密钥
`EMAIL_NOT_VERIFIED`	403	开发者邮箱未验证	先完成邮箱验证
`INVALID_IDEMPOTENCY_KEY`	400	幂等键缺失或格式无效	生成 8～128 位安全字符
`IDEMPOTENCY_CONFLICT`	409	同一幂等键用于不同请求	为新请求生成新幂等键
`BALANCE_INSUFFICIENT`	409	可用积分不足	充值后用同一请求重试
`FINAL_FILES_NOT_READY`	409	预览尚未完成或成品文件未准备好	等待 result.status=preview_ready 后再确认成品
`API_RATE_LIMIT`	429	用户或密钥分钟配额已用完	遵循 Retry-After 后重试
`API_CONCURRENCY_LIMIT`	429	任务并发数达到上限	等待已有任务结束
`FILE_EXPIRED`	410	资源已过期	重新创建任务
`API_UNAVAILABLE`	503	接口暂时不可用	指数退避并保持相同幂等键

质量问题出现在任务的结构化 error 或 quality.issues 中。它们需要更换输入图片，不应自动反复提交原图。