如果某项功能无法正常运行，判断问题出在你这边还是我们这边，最快的方法是用另一个工具发送相同的请求。

约 90% 的「API 故障」报告，最终都是 base URL 配置错误、API key 已过期、模型名称拼写错误，或请求体格式来自落后了三个 SDK 版本的教程。

快速自检

将下方 curl 命令粘贴到终端，把 YOUR_KEY 替换为 Dashboard 中你的 API key 并运行。若能收到正常的补全结果，说明你的 API key、网络连接和我们的后端均运行正常 — 问题在于你的客户端代码或环境配置。

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

ℹ️

快速自检: 没有终端？把相同的模型和 prompt 粘贴到 Dashboard 的 Playground 中 — 效果相同，无需任何配置。

逐步检查清单

你的 API key 是否有效？

打开 Dashboard → API Keys，确认 key 与你代码中使用的一致。常见陷阱是复制粘贴时在 "sk-air-" 前缀前混入了空白字符。

症状：401 Unauthorized。

base URL 是否正确？

base URL 必须为 https://api.airforce/v1 — 不能用 http，且必须带 /v1 后缀。早于 OpenAI v1 路径的教程有时会省略该后缀。

症状：404 Not Found，或 curl 挂起无响应。

模型名称拼写是否正确？

模型 ID 区分大小写。请访问 Models 页面或调用 GET /v1/models 确认完整 ID。拼写错误或已弃用的模型会返回明确的错误，而不是「能运行但结果不对」。

症状：400 unknown_model 或 404 model_not_found。

请求体格式是否正确？

聊天补全使用 messages 数组；图像生成使用 prompt + n；音频 TTS 使用 input + voice。将聊天格式的请求体发送到 /v1/images/generations 会返回 400 — 在不同文档间复制片段时很容易出错。

症状：400，响应体中会指明出错的字段。

是否已触达速率限制或配额上限？

429 = 本分钟请求次数过多；402 = 套餐或余额已耗尽。两者均可在 Dashboard 中查看。免费套餐请求与付费套餐请求的限额相互独立，因此付费模型可能正常响应，而免费模型却触发限流。

症状：429 Too Many Requests 或 402 Payment Required。

该模型当前是否可用？

请查看 Models 页面 — 上游服务商故障会显示为「degraded」或「major outage」。如果某个模型不可用而其他模型正常，这是我们正在绕行的上游问题，而非客户端错误。

症状：特定模型返回 5xx，而其他模型正常。

HTTP 状态码含义

每个错误响应都携带标准的 HTTP 状态码。了解每个状态码的含义可以避免不必要的工单。


400	你这边	Bad Request — JSON 格式错误、缺少必填字段或包含未知参数。请修正请求体。
401	你这边	Unauthorized — API key 缺失或无效。请检查 Authorization 请求头是否包含 "Bearer " 前缀。
402	你这边	Payment Required — 套餐额度已耗尽或 Pay-as-you-go 余额不足。请订阅或充值。
403	你这边	Forbidden — 你的套餐或 per-key 权限不允许使用该模型或 endpoint。
404	你这边	Not Found — endpoint 或模型 ID 不存在。请检查 URL 路径和模型名称拼写。
413	你这边	Payload Too Large — 输入内容超出模型的上下文窗口。请缩短 prompt。
429	你这边	Too Many Requests — 请求已被限流（RPM、RPD 或每日 token 上限）。请降低请求频率或升级套餐。
500	我们这边	Internal Server Error — 我们这边出现了 Bug。如果持续超过一分钟，请上报。
502	我们这边	Bad Gateway — 后端正在重启（我们每天会部署数次）。等待 5–10 秒后重试。
503	我们这边	Service Unavailable — 该模型的所有上游提供商同时故障。如果持续超过几分钟，请上报。

💡

判断原则: 4xx 状态码表示客户端发送的请求被服务器拒绝；5xx 状态码表示我们在处理合法请求时出现了错误。响应中的 JSON 错误体通常会指明触发检查的字段。

真正的 Bug 是什么情况

如果上方 curl 自检通过，但完全相同的请求在你的代码中却失败，问题出在你的客户端（或其所用的库）。如果自检本身返回 5xx，或返回的 4xx 信息与你的请求内容不符，那才值得上报。

如何有效上报问题

通过 Dashboard 提交支持工单，或在 Discord 的 #support 频道发帖。请附上：

完整的 HTTP 状态码及响应体（如有，也请附上 cf-ray 响应头）。
UTC 时间的大致时间戳。
模型名称及所调用的 endpoint。
能复现问题的最小 cURL 示例（请遮盖真实 API key！）。
用同一个 key 执行上方自检时，结果是否通过。

ℹ️

如何有效上报问题: 附带以上信息的工单通常一次即可得到实质性答复。缺少这些信息的工单几乎每次都需要来回沟通才能帮到你。

在 Discord 的 #support 频道提问

上报 Bug 前请先检查