故障排查

遇到请求失败时，按下面顺序排查，通常可以快速定位问题。

1. API Key

检查请求头是否正确：

Authorization 格式

bash

Authorization: Bearer sk-your-api-key

不要写成：

缺少 Bearer；
Bearer 和 Key 之间没有空格；
Key 前后有不可见空格；
使用了已删除或禁用的 Key。

2. Base URL

正确地址：

https://sparkapi.org/v1

错误示例：

错误	说明
`https://sparkapi.org`	缺少 `/v1`
`http://sparkapi.org/v1`	应使用 HTTPS
地址前后有空格或换行	SDK 可能解析失败

3. 模型名

模型名必须与控制台展示一致。注意大小写、连字符和版本后缀。

4. 余额和倍率

余额不足、高倍率模型或输出过长都可能导致请求失败或消耗异常。先用轻量模型和短输出测试。

5. 请求频率

如果出现 429：

降低并发；
增加重试退避；
缩短批量任务；
检查是否多个任务共用同一个 Key；
联系技术支持确认限额。

6. SDK 配置

Python SDK 快速自检

python

from openai import OpenAI

client = OpenAI(
  api_key="sk-your-api-key",
  base_url="https://sparkapi.org/v1",
)

print(client.chat.completions.create(
  model="gpt-4o-mini",
  messages=[{"role": "user", "content": "ping"}],
).choices[0].message.content)

7. 上游错误

如果确认 Key、Base URL、模型名、余额和请求格式都正确，但仍然出现 500、502 或超时，可能是上游模型或网络问题。建议稍后重试，或切换备用模型。

1. API Key​

2. Base URL​

3. 模型名​

4. 余额和倍率​

5. 请求频率​

6. SDK 配置​

7. 上游错误​