错误处理

PinduCloud 返回 OpenAI 兼容的错误对象。业务系统应结合 HTTP 状态码和 error.code 判断是否重试、修正请求或触发告警。

错误对象

{
  "error": {
    "message": "The request is invalid.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}

请求示例

curl https://pinducloud.cc/v1/chat/completions \
  -H "Authorization: Bearer $PINDUCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "unknown-model",
    "messages": [
      {
        "role": "user",
        "content": "Hello"
      }
    ]
  }'

响应示例

{
  "error": {
    "message": "The model `unknown-model` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

常见错误

HTTP 状态码	Code	是否重试	说明
400	invalid_request	否	请求体或参数不合法
401	invalid_api_key	否	API Key 缺失或无效
403	permission_denied	否	当前 API Key 无权访问资源
404	model_not_found	否	模型不存在或不可用
429	rate_limit_exceeded	是	请求频率或额度超限
500	internal_error	是	服务内部错误
503	service_unavailable	是	服务暂不可用

处理建议

• 400、401、403、404 不应在不修改请求的情况下反复重试。
• 429、500、503 可使用指数退避重试，并设置最大重试次数。
• 日志中应移除 API Key 和敏感用户数据。