错误处理

错误格式

SeaCloud LLM 可能返回简洁错误，也可能返回 OpenAI 风格错误对象。客户端应按状态码和错误码共同处理。

鉴权错误

缺少 token

{
  "error": "missing authentication token"
}

无效 key

{
  "error": "invalid_api_key"
}

余额不足

{
  "error": "insufficient balance"
}

OpenAI 风格错误

{
  "error": {
    "message": "Request rejected by quota policy.",
    "type": "rate_limit_error",
    "param": null,
    "code": "quota_exceeded"
  }
}

常见 HTTP 状态

状态码	常见原因	处理建议
401	缺少鉴权 token	检查 Authorization 或 x-api-key
403	API Key 无效、过期、余额不足或模型未授权	不要无限重试，先处理账号或权限问题
404	路径不支持或公网入口不正确	核对公网路径必须带 /llm
429	配额或速率限制	按 Retry-After 或指数退避重试
502/503/504	服务暂时不可用或请求超时	记录 X-Request-Id 并联系平台排查

客户端建议

• 记录 HTTP 状态码、响应体和 X-Request-Id
• 只对 429 和部分 5xx 做有限退避重试
• 对鉴权、余额、模型权限和路径错误，应修正配置后再重试
• 流式请求中途断开时，不要假设本次请求不会产生用量或计费