错误处理与 HTTP 状态码

当 API 请求发生异常或无法正常处理时，网关将返回标准的 HTTP 状态码及 JSON 格式的详细错误原因。

---

1. 错误 JSON 响应格式

所有错误响应均遵循标准 OpenAI Error Schema：

{
  "error": {
    "message": "Invalid API Key provided",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

---

2. HTTP 状态码对照表

HTTP 状态码	错误类型 (Error Type)	原因说明	排查建议
400	invalid_request_error	请求参数格式错误或必填字段缺失	检查 JSON 体语法，确认必填字段（如 model, prompt）正确
401	authentication_error	API Key 无效、过期或未正确传输 Header	检查 Authorization: Bearer sk-xxx 请求头是否泄漏或写错
402	insufficient_quota	账户可用余额不足	请在控制台进行账户充值后再发起请求
404	not_found_error	请求的 API 路径或模型 ID 不存在	确认 URL 是否加上 /v1 前缀及模型名称正确
429	rate_limit_error	请求频率超出当前分组限流上限	适当降低并发或联系管理员提高限流配额
500	api_error	网关内部或底层供应商节点故障	重试请求或切换至备用节点 https://api.ximi-pro.xyz/v1
504	gateway_timeout	底层 upstream 响应超时	对于长耗时任务，建议使用 异步生图 API