Api.Airforce
トラブルシューティング

バグを報告する前に

「バグ」のほとんどは 60 秒で直せる設定の問題です — まずこのチェックリストを確認してください。

何かがうまく動かない場合、問題があなたの側にあるのか私たちの側にあるのかを最も素早く確認するには、別のツールから同じリクエストを実行してみてください。

「API が壊れている」というレポートの約 9 割は、誤った base URL の設定、古い API キー、モデル名のタイポ、または 3 世代前の SDK バージョン向けチュートリアルのリクエストボディの形式が原因であることが判明しています。

クイック セルフテスト

この curl コマンドをターミナルにコピーしてください。YOUR_KEY を Dashboard の API キーに置き換えて実行します。通常のレスポンスが返ってくれば、API キー・ネットワーク・バックエンドはすべて正常です — 問題があるとすればクライアントコードまたは環境側です。

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"}]
  }'
ℹ️
クイック セルフテスト: ターミナルがすぐに使えない場合は、同じモデルとプロンプトを Dashboard の Playground に貼り付けてください — 同じ効果が得られ、セットアップ不要です。

ステップバイステップ チェックリスト

API キーは有効ですか？

Dashboard → API Keys を開き、キーがコードで使用しているものと一致していることを確認してください。よくある罠は、コピー＆ペースト時に "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 = この 1 分間のリクエスト数が多すぎます。402 = プランまたは残高が枯渇しています。どちらも Dashboard で確認できます。無料枠のリクエストと有料プランのリクエストは上限が別々に設定されているため、有料モデルは正常に応答しても無料モデルはレート制限される場合があります。

症状: 429 Too Many Requests または 402 Payment Required。

そのモデルは現在稼働していますか？

Models ページを確認してください — プロバイダーの障害は「degraded」または「major outage」として表示されます。あるモデルがダウンしていても他が動作している場合は、私たちがルーティングで回避しているプロバイダー側の問題であり、クライアントエラーではありません。

症状: 特定のモデルだけ 5xx を返し、他は動作している。

HTTP ステータスコードの意味

すべてのエラーレスポンスには標準の HTTP ステータスコードが含まれています。各コードの意味を把握しておくとチケット提出の手間が省けます。

400あなたの側Bad Request — 不正な JSON、必須フィールドの欠落、未知のパラメーター。リクエストボディを修正してください。
401あなたの側Unauthorized — API キーがないか無効です。Authorization ヘッダーに "Bearer " プレフィックスが含まれているか確認してください。
402あなたの側Payment Required — プランの使用量超過または Pay-as-you-go の残高が不足しています。サブスクライブするかチャージしてください。
403あなたの側Forbidden — プランまたはキー単位の権限では、このモデルまたはエンドポイントは使用できません。
404あなたの側Not Found — 未知のエンドポイントまたはモデル ID です。URL パスとモデル名のスペルを確認してください。
413あなたの側Payload Too Large — 入力がモデルのコンテキストウィンドウを超えています。プロンプトを短くしてください。
429あなたの側Too Many Requests — レート制限に達しました（RPM、RPD、または 1 日あたりのトークン上限）。リクエストを減らすかプランをアップグレードしてください。
500私たちの側Internal Server Error — 私たちの側のバグです。1 分以上続く場合は報告してください。
502私たちの側Bad Gateway — バックエンドが再起動中です（1 日に数回デプロイしています）。5〜10 秒待ってからリトライしてください。
503私たちの側Service Unavailable — そのモデルのすべてのアップストリームプロバイダーが同時に失敗しました。数分以上続く場合は報告してください。
💡
判断の目安: 4xx コードはクライアントがサーバーに拒否された操作を行ったことを意味します。5xx コードは有効なリクエストを私たちの側で処理できなかったことを意味します。レスポンスの JSON エラーボディには通常、チェックに引っかかったフィールド名が記載されています。

本当にバグである場合

上記の curl セルフテストは成功するのに、コードからまったく同じリクエストを送ると失敗する場合、問題はクライアント（またはそれが使用しているライブラリ）にあります。セルフテスト自体が 5xx で失敗する場合、またはリクエストの内容と一致しないメッセージを伴う 4xx が返ってくる場合は、報告する価値があります。

効果的なバグ報告の方法

Dashboard からサポートチケットを開くか、Discord の #support に投稿してください。以下の情報を含めてください：

  • 完全な HTTP ステータスコードとレスポンスボディ（存在する場合は cf-ray レスポンスヘッダーも）。
  • UTC での発生時刻の概算。
  • モデル名と呼び出したエンドポイント。
  • 再現できる最小限の cURL（実際の API キーはマスクしてください！）。
  • 同じキーで上記のセルフテストが成功するかどうか。
ℹ️
効果的なバグ報告の方法: これらの詳細が揃ったチケットは初回で正確な回答が得られます。情報が不足しているチケットはほぼ必ず、対応できるまでに何度かやり取りが必要になります。

Discord の #support で質問する

設定でお困りですか？無料キーが欲しいですか？Discordのコミュニティに聞いてみましょう。

Discordに参加する