Errors

错误码

所有 4xx / 5xx 含义 + 处理建议。Solquir 错误格式跟 OpenAI 兼容（type + message）但加了 traceId。

错误响应格式

json

{
  "error": {
    "type": "rate_limited",
    "message": "Too many requests. Try again in 12s.",
    "traceId": "trc_0xK2w..."
  }
}

NOTE报问题给 support@solquir.com 时附上 traceId 能快速定位（不用整个请求 body）。

HTTP	type	含义	处理建议
400	`invalid_request`	请求 body / 参数不合法（如 messages 为空、temperature 超出 0-2）	❌ 修请求后再发
401	`invalid_api_key`	Bearer token 缺失 / 无效 / 已 revoke	❌ 检查 SOLQUIR_API_KEY
403	`permission_denied`	Key 没访问该模型 / endpoint 的权限	❌ 在 dashboard 升级订阅
404	`not_found`	Model slug 不存在 / endpoint 路径错	❌ 见 /docs/models
429	`rate_limited`	RPM / TPM 限制触发，需要降速	✅ 退避指数（exp backoff）后重试，看 X-RateLimit-Reset header
500	`internal_error`	Solquir 内部错误（罕见，oncall 已收到告警）	✅ 等几秒重试，反复出现请联系 support
502	`upstream_error`	上游 provider（如 OpenAI / Anthropic）返错；Solquir 路由器未自动 fallback	✅ 重试 1-2 次；持续出现联系 support
503	`model_misconfigured`	Admin 配错路由 / 上游全部失效，模型暂时不可用	❌ 等 admin 修。可换其它 model 临时跑
504	`upstream_timeout`	上游响应超时（>120s）	✅ 减少 max_tokens 或拆请求