错误处理

错误响应格式

Token8 的错误响应格式与 OpenAI API 对齐，方便 SDK 统一处理：

{
  "error": {
    "message": "Validation failed",
    "type": "invalid_request_error",
    "code": "validation_error",
    "details": [
      { "path": "prompt", "message": "Required" }
    ]
  }
}

错误类型

type	说明
`invalid_request_error`	请求参数有误
`auth_error`	API Key 无效、已禁用或过期
`billing_error`	余额不足或定价未配置
`routing_error`	无可用供应商
`not_found`	资源不存在
`server_error`	配置错误（如 JWT_SECRET 缺失）
`api_error`	Token8 内部未知错误

HTTP 状态码

状态码	type	处理建议
400	`invalid_request_error`	检查请求参数
401	`auth_error`	检查 API Key 是否正确
402	`billing_error`	余额不足，充值后重试
403	`auth_error`	API Key 已禁用或过期
404	`not_found`	资源不存在
429	`billing_error`	Token 额度耗尽
500	`server_error` / `api_error`	联系支持或稍后重试
503	`routing_error`	无可用供应商，稍后重试

任务级错误

任务执行过程中的错误体现在 GET /v1/tasks/:task_id 的响应中：

{
  "task_id": "task_abc123def456",
  "status": "failed",
  "error": {
    "code": "provider_failure",
    "message": "Upstream provider returned error: content policy violation"
  }
}

任务错误码

code	说明	是否自动重试
`provider_failure`	上游商家返回错误	✅ 自动切换商家
`provider_timeout`	上游超时	✅ 自动切换商家
`content_policy`	内容违规被拒绝	❌ 不重试
`all_providers_failed`	所有候选商家均失败	❌ 返回失败
`quota_exhausted`	执行中余额耗尽	❌ 退费

开启「图片/视频生成重试」后，provider_failure 和 provider_timeout 会自动切换商家，直到达到最大尝试次数。