Qwen API トラブルシューティング：401 / 404 / 429 / 503 / タイムアウトの切り分け
Qwen API トラブルシューティング
OpenAI 互換エンドポイントを呼び出すとき、もっとも時間を浪費するのは「エラーコードは出ているのに何を直せばいいか分からない」状態です。401、404、429、503、タイムアウト — それぞれ原因が違うので、闇雲に試すのではなく決まった順序で切り分けます。この記事は Qwen 系をはじめとするモデル呼び出し全般に使える手順です。
30 秒でわかる要点
診断順序は固定です：① Key ② URL ③ モデル ID ④ サービス状態。まず curl で最小リクエストを打ち、生の HTTP ステータスとレスポンス本文を確認します。401 は Key、404 は URL パス、model-not-found は ID、429 はバックオフ付き再試行、503 は回数限定の再試行、タイムアウトはネットワークとリクエストサイズを確認します。
まず curl で最小リクエストを打つ
ビジネスコードを触る前に、最小の再現リクエストを curl で実行します。SDK はエラーをラップして元のレスポンスを隠すことがあるため、生のステータスコードと本文が見える curl が最も確実です。
curl -sS https://exaiv.com/api/ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "kimi-k3",
"messages": [{"role": "user", "content": "hi"}]
}'
モデル ID は /models ディレクトリのリアルタイム情報に従ってください。HuggingFace の重み名を入れてもリクエストは通りません。
401：Key または認証ヘッダ
401 Unauthorized は認証されていないことを意味します。よくある 3 原因：
| 原因 | 確認項目 |
|---|---|
| Key が無効・形式不良 | 完全にコピーしたか、前後に空白がないか、失効していないか |
| ヘッダ形式不良 | Authorization: Bearer の接頭辞があるか |
| アカウント違い | コンソールの Key が現在のサイトのものか |
最小の修復手順：Key を再生成し、前後の空白なしで貼り付け、curl を再実行します。
Bearer 接頭辞を忘れない
Authorization ヘッダの値は Key そのものではなく Bearer <Key> です。接頭辞の欠落や余分な空白が 401 の典型原因です。
404：パスまたはモデル
404 Not Found の主な原因は 2 つです。
1. URL パス不正。 正しい Chat Completions エンドポイントは /api/ai/v1/chat/completions です。よくある誤り：
/api/ai/v1の層が抜ける（https://exaiv.comや/v1のみ）/v1を二重に書く（/api/ai/v1/v1/chat/completions）
2. モデル ID 不正。 ID は /models カタログの実在するものだけが有効です。qwen3.8-flash-next や Qwen/Qwen3.8-Flash-Next のような重み名を入れても失敗します。
429：レート制限
429 Too Many Requests は「少し後で再試行して」というサービスからの明示的な合図です。指数バックオフで再試行します：
import time
import openai
client = openai.OpenAI(api_key="YOUR_API_KEY", base_url="https://exaiv.com/api/ai/v1")
def call_with_retry(messages):
for attempt in range(4):
try:
return client.chat.completions.create(model="kimi-k3", messages=messages)
except openai.RateLimitError:
time.sleep(2 ** attempt) # 2, 4, 8 秒
raise RuntimeError("4 回再試行してもレート制限中")
429 はサービス停止ではありません
429 は「忙しい」という能動的な応答であり、バックオフでほぼ解消します。再試行なしで即座に失敗扱いにしないでください。一方、永続的に 429 が出る場合は並行数の仕様調整が必要です。
503 とタイムアウト
503：一時的なサービス不能。回数を限定（3〜4 回）して短いバックオフで再試行し、それでも駄目ならフォールバックまたは失敗終了します。無制限の再試行は状況を悪化させます。
タイムアウト：HTTP ステータスではなく、クライアントが規定時間内に完全な応答を受け取れなかった状態です。確認順：
--max-time 30付きの curl でもタイムアウトするか — するならネットワーク経路の問題- リクエストが大きすぎないか — 長いコンテキスト、大きな
max_tokensを縮めて再試行 - プロキシや VPN が経路にないか
モデル未検出とカタログの関係
「モデルが存在しない」と言われたら、まずコードではなくカタログを確認します。Qwen 系を含むクラウドの提供 ID は上流更新に合わせて変動します。/models のリアルタイム一覧にない ID は、どんなに命名が正しそうでも呼び出せません。HuggingFace のオープン重み名は API ID ではありません — この混同が最も多い原因です。
重み名を API ID にしない
Qwen/Qwen3.8-Flash-Next は HuggingFace の重み名であり、API ID ではありません。API ID はプラットフォームのカタログが公開している文字列だけです。混在させないでください。
診断順序のまとめ
| ステップ | 確認 | 対応 |
|---|---|---|
| 1 | Key | 再生成、空白除去 |
| 2 | URL | /api/ai/v1/chat/completions まで過不足なく |
| 3 | モデル ID | /models の実在 ID に修正 |
| 4 | サービス状態 | 回数限定の再試行、フォールバック |
| 5 | ネットワーク | curl で確認、リクエスト縮小 |
FAQ
401 は必ず Key の問題ですか？
404 は URL とモデルのどちらですか？
429 の再試行は何回が適切？
タイムアウトと 429 の違いは？
モデル ID はどこで確認しますか？
価格はどこで見られますか？
関連記事
- Qwen モデル選びガイド — 家族の使い分け
- Kimi K3 vs GLM-5.3 比較 — 在售双モデル
- ローカルデプロイ完全プレイブック — ローカル端点の構築
- モデルカタログ — 現在利用可能な ID