错误处理

错误响应格式

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",
  "model": "gpt-image-2",
  "fail_reason": "content_policy_violation",
  "message": "提示词或参考图未通过内容安全检测，请修改后重试",
  "total_cost": 0,
  "attempt_count": 1
}

常见任务失败原因

fail_reason	说明	是否自动重试
`upstream_500` / `upstream_503`	上游商家返回服务错误	是
`timeout_120s` / `timeout_240s`	上游提交超时	是
`poll_timeout`	异步任务轮询超时	是
`content_policy_violation`	提示词或参考图未通过内容安全检测	否
`upstream_quota_exhausted`	当前上游渠道额度不足，系统暂时无法完成请求	是
`no_more_providers`	已无可切换商家	否
`insufficient_user_quota` / `insufficient_token_quota`	重试预扣费时额度不足	否

Auto Key 会按系统配置处理可恢复的上游失败并自动切换商家。达到系统配置的尝试上限后任务终止，失败 attempt 的费用会自动退回。内容安全失败会直接终止任务，不会因为无可切换商家而包装成 no_more_providers。公开任务响应只返回归一化错误码和可展示消息；上游响应正文、渠道账户余额和上游请求 ID 不会返回给 API 调用方。