著者注：curl では接続できるのに、クライアントで 401、404、400 が返る、または接続できない場合に向けて、API中継サービスの7つのチェックポイントを決まった順序で確認します。エラーコード対照表と10分間のトラブルシューティングチェックリストも掲載しています。
同じ Key、同じモデルを使い、curl でリクエストすると 200 が返るのに、Cherry Studio、Chatbox、Cursor、Cline、Claude Code、Codex CLI では 401、404、400 が返る、あるいはタイムアウトや空の応答になる。そんなときは、Key を交換する前に、まずクライアントの設定を疑いましょう。curl で接続できるなら、Key が有効でネットワークも到達可能だと確認できています。問題は、クライアントが実際に送信しているリクエストと、想定しているリクエストの違いにある可能性が高いでしょう。
おすすめの確認順序は、Base URL → プロトコルとエンドポイント → 認証ヘッダー → モデル ID → リクエストボディ → ネットワークです。その前に、クライアントが変更後の設定を実際に読み込んでいるかも確認しましょう。この記事では、リクエストの経路を7つのチェックポイントに分け、それぞれを「現象、原因、検証方法、修正方法」の順に解説します。10分以内に、問題がクライアント、ゲートウェイ、上流のどこにあるかを判断することが目標です。
これは単なる API の仕組みの解説記事ではありません。手順に沿ってすぐに実行できる、トラブルシューティングマニュアルです。
curl では接続できるのにクライアントでは接続できない：API中継のトラブルシューティング
curl が検証するのは、通信経路の一部分だけです。DNS解決、TLSハンドシェイク、ネットワークへの到達性、キーの有効性、そして手動でリクエストした一つのエンドポイントが利用できることを確認できます。一方、変更した設定をクライアントが読み込んだか、Base URLをどう組み立てたか、クライアントのリクエストヘッダーとリクエストボディが curl と一致しているかは検証できません。
クライアントから送信されたリクエストは、おおむね次の経路をたどります。クライアント設定（環境変数、設定ファイル、GUI）→ Base URLの組み立て → プロトコルとエンドポイント → 認証ヘッダー → モデルIDとマッピング → リクエストボディ（メッセージ、ツール、マルチモーダル、ストリーミング）→ プロキシ、TLS、ネットワーク → ゲートウェイ → 接続先モデル。curl で接続できても、それは手動で指定した経路が使えるということにすぎません。クライアントはまったく別の経路を通っている可能性があります。
| チェックポイント | 典型的な症状 | 優先して確認する方法 |
|---|---|---|
| 1. 設定の読み込み | 設定を変更しても反映されず、変更前と同じエラーが出る | クライアントのログで実際のリクエストURLを確認する |
| 2. Base URLの組み立て | 404が返る、パスに /v1/v1 や // が含まれる |
ログのURLと curl のURLを比較する |
| 3. プロトコルとエンドポイント | 404、400、またはレスポンス形式の解析エラーが出る | クライアントが使用しているプロトコルを確認する |
| 4. 認証ヘッダー | curl ではキーが正常に使えるのに、401が返る | リクエストヘッダーの違いを比較する |
| 5. モデルID | 404または400が返り、モデルが存在しないと表示される | ゲートウェイのモデル一覧と一文字ずつ照合する |
| 6. リクエストボディ | テキストのみなら接続できるが、画像やツールを追加すると400が返る | 変数を一つずつ追加して再現する |
| 7. ネットワークとストリーミング | タイムアウト、stream disconnected、空の応答が発生する | ストリーミングをオフにして比較し、プロキシを確認する |
API中継サービスのチェックポイント 1-2：クライアント設定の読み込みと Base URL の結合
チェックポイント 1：変更した設定をクライアントが読み込んでいるか
症状：Base URL と APIキーを新しいものに変更したのに、変更前とまったく同じエラーが出る。あるいは、あるプロジェクトでは使えるのに、別のプロジェクトでは使えない。
原因：多くのクライアントは、複数の場所から設定を読み込みます。よくあるのは、GUI の設定が環境変数を上書きしている、設定ファイルに複数の profile があり、変更したものが有効になっていない、プロジェクト単位の設定がグローバル設定を上書きしている、古いプロセスが終了せず起動時に読み込んだ設定を使い続けている、といったケースです。特にコマンドラインツールでは、ターミナルで環境変数を変更しても、すでに起動している IDE や Agent のプロセスには反映されないことがあります。
確認方法：クライアントのログやデバッグ出力を開き、実際のリクエスト URL と APIキーの先頭数文字が、変更後の値になっているか確認します。ログを確認しにくい場合は、Base URL を意図的に明らかに間違ったアドレスに変更し、エラーが変わるかどうかで設定が反映されているか確認できます。
対処方法：まず、そのクライアントの設定の優先順位を確認します。一般的には GUI やプロジェクトの設定がグローバル設定ファイルより優先され、設定ファイルは環境変数より優先されます。ただし、ルールはクライアントによって異なるため、ドキュメントを確認してください。そのうえで、優先順位が最も高い場所だけを変更し、ほかの場所にある競合する設定を削除して、クライアントのプロセスを完全に終了してから再起動します。
チェックポイント 2：Base URL 末尾のスラッシュ、/v1 の重複とパスプレフィックス
症状：404 エラーが出る。ログ内の URL が /v1/v1/chat/completions や //chat/completions になっている、または /v1/chat/completions/chat/completions になっている。
原因：Base URL の入力欄に何を指定するかは、クライアントによって異なります。ルートアドレスを入力すると /v1 を自動的に追加するものもあれば、/v1 まで入力すると /chat/completions を追加するものもあります。また、Base URL と完全なエンドポイントを別々の入力欄に指定するものもあります。プレフィックスだけを受け付ける入力欄に https://api.apiyi.com/v1/chat/completions を丸ごと入力したり、すでに /v1 が付いているアドレスの末尾にスラッシュを追加したりすると、結合後のパスが誤ったものになります。
確認方法：ログに記録された完全なリクエスト URL と、curl で使用した URL を一文字ずつ比較します。特に、/v1 が何回現れるか、二重スラッシュがないか、末尾に余分なパスが付いていないかを確認してください。
対処方法：クライアントのドキュメントに従って入力します。OpenAI 互換のクライアントでは、通常 https://api.apiyi.com/v1 を末尾のスラッシュなしで入力します。クライアントが /v1 を自動的に追加する場合は、手入力した /v1 を削除してください。変更後はもう一度ログの URL を確認し、最終的なパスが https://api.apiyi.com/v1/chat/completions のような標準的な形式になっているか確かめます。
🎯 設定のヒント：APIYI（apiyi.com）の OpenAI 互換の接続先は
https://api.apiyi.com/v1で、公式 OpenAI SDK と同じ書き方です。利用可能なモデルの一覧はコンソールで確認できるほか、同じ Base URL からモデル一覧 API をリクエストして取得することもできます。まずはそれを使って APIキーとアドレスが正しいことを確認してから、クライアントを設定しましょう。
API中継サービスの確認ポイント 3〜4：プロトコルのエンドポイントと認証ヘッダー
チェックポイント 3：プロトコルとエンドポイントが一致しているか
症状：Base URL に問題はなさそうなのに、404 や 400 が返される。あるいは、リクエストは成功しているものの、クライアントに「レスポンスを解析できません」と表示されたり、空の内容が返されたりする。
原因：現在、主流の大規模言語モデルのインターフェースには複数のプロトコルがあります。例えば、クライアントが Chat Completions にしか対応していないのに、Responses しか公開していないエンドポイントを指定している場合です。Claude Code が使うのは Anthropic Messages プロトコルであり、OpenAI Chat Completions ではありません。また、Gemini のネイティブ形式と OpenAI 互換形式では、パスもリクエストボディもまったく異なります。curl では正しいエンドポイントを手動で指定していても、クライアントは独自のデフォルトプロトコルでリクエストを送ることがあります。
| プロトコルの種類 | 代表的なエンドポイントパス | 主な利用元 | 認証方式 |
|---|---|---|---|
| OpenAI Chat Completions | /v1/chat/completions |
Cherry Studio、Chatbox、Cline など、多くのクライアント | Authorization: Bearer |
| OpenAI Responses | /v1/responses |
新しい OpenAI エコシステムのツール | Authorization: Bearer |
| Anthropic Messages | /v1/messages |
Claude Code などの Anthropic ネイティブツール | x-api-key と anthropic-version |
| Gemini ネイティブ | モデル名をパスに含むネイティブ API | Gemini ネイティブ SDK | 公式ドキュメントとゲートウェイのドキュメントを参照 |
確認方法：クライアントのログでリクエストパスの末尾を見て、どのプロトコルが使われているかを確認します。そのうえで、選択したゲートウェイのエンドポイントがそのプロトコルに対応しているかを確認してください。クライアントに「プロバイダーの種類」や「API 形式」のドロップダウンがある場合は、使いたいプロトコルに合った選択肢を選びます。
対処方法：クライアントのプロトコルの種類、Base URL、モデルの3つを揃えます。OpenAI 互換形式を使うなら OpenAI 系のプロバイダーを選び、Claude Code のようなネイティブツールは Anthropic プロトコルに従って設定します。Gemini のネイティブ機能が必要な場合は、Gemini 形式で設定してください。APIYI は OpenAI 互換形式と Claude、Gemini などのネイティブ API 形式の両方に対応しています。各ネイティブ形式の具体的な接続先は docs.apiyi.com のドキュメントを確認し、記憶を頼りにパスを組み立てないようにしましょう。
チェックポイント 4：認証ヘッダーがプロトコルに合っているか
症状：401 エラーが出るものの、同じキーは curl では問題なく使える。
原因：OpenAI 互換 API では通常 Authorization: Bearer <Key> を使います。一方、Anthropic ネイティブ API では通常 x-api-key と anthropic-version を使います。プラットフォームによっては、組織やプロジェクトに関連するリクエストヘッダーも必要です。curl では正しいヘッダーを指定していても、クライアントが別のプロトコルに従って異なるヘッダーを送信したり、ゲートウェイが認識しない組織ヘッダーを付けたりすると、認証に失敗します。
確認方法：curl とクライアントのログにあるリクエストヘッダーを比較し、特に Authorization、x-api-key、Content-Type、OpenAI-Beta などのフィールドを確認します。キーの前後に余分なスペース、改行、引用符がないかも確認しましょう。Webページからコピー＆ペーストする際によく起こる問題です。
対処方法：認証ヘッダーはプロトコルに合わせます。正しいプロトコルを選べば、ほとんどのクライアントは適切なヘッダーを自動で送信します。クライアントでリクエストヘッダーをカスタマイズできる場合は、不要な組織ヘッダーやプロジェクトヘッダーを削除してください。また、キーを貼り直し、余分な文字が入っていないことを確認します。
API中継のトラブルシューティング：チェックポイント5〜7――モデルID、リクエストボディ、ネットワークとストリーミング
チェックポイント5：モデルIDとモデルマッピング
現象：404や400のエラーが発生し、モデルが存在しない、または無効だと表示されます。あるいは、特定のモデルだけが失敗し、ほかのモデルは正常に動作します。
原因：モデルIDは、ゲートウェイのモデル一覧と一字一句一致している必要があります。よくある違いには、大文字・小文字、バージョンの接尾辞、プレフィックスの書き方（provider/model 形式など）、エイリアスがあります。同じモデルでもプラットフォームによって名前が異なる場合があります。また、クライアント内蔵のモデル一覧に目的のIDがなく、知らないうちにデフォルト値へ切り替わっていることもあります。
確認方法：ゲートウェイのモデル一覧APIまたはコンソールからモデルIDをコピーし、クライアントのログに記録されたリクエストボディの model フィールドと一字一句照合します。特定のモデルだけが失敗する場合は、まずモデルIDとエンドポイントが一致しているかを確認し、次にアカウントにそのモデルへのアクセス権限があるかを調べます。
修正方法：クライアントでカスタムモデルを手動で追加し、ゲートウェイが示すIDを直接貼り付けます。手入力は避けましょう。クライアントがモデルマッピングを行う場合は、マッピング後の名前が正しいことも確認してください。
💡 モデルIDのヒント：APIYI apiyi.com を通じて1つのキーでOpenAI、Claude、Gemini、DeepSeek、Qwenなど複数社のモデルを呼び出す場合は、コンソールのモデル一覧に記載されたIDを使用してください。同じモデルでもプラットフォームによって名前が異なるため、コンソールからコピーするのが最も手軽で確実です。モデルの利用可否もコンソールとドキュメントで確認してください。
チェックポイント 6：リクエストボディとマルチモーダル形式
症状：テキストだけの会話は正常に動くのに、画像を送信したり、ツールを呼び出したり、推論パラメータを有効にしたりすると 400 エラーが出る。
原因：リクエストボディの互換性に関する問題は、主に次の箇所で起こります。マルチモーダルの content 配列の構造、image_url フィールドの記述方法、base64 画像の data:image/png;base64, のような MIME プレフィックスの不足、ツール呼び出しのフィールド形式が現在のプロトコルに合っていないことなどです。また、max_tokens と max_completion_tokens の要件はモデルによって異なり、reasoning 関連のパラメータを受け付けるのは一部のモデルだけです。各メーカーのパラメータは完全に共通ではありません。
確認方法：変数を段階的に追加します。まずテキストのみを送信し、成功したらストリーミングを有効にし、次にツール呼び出し、最後にマルチモーダル入力を追加します。変数を一つ追加するたびにテストし、どの段階から失敗するかで問題のあるフィールドを特定します。エラーメッセージには通常、具体的なフィールドが示されているので、エラーレスポンス全体を確認しましょう。
対処方法：クライアントで不要な高度なパラメータを無効にし、対象モデルのドキュメントに従ってフィールドを調整します。画像には正しい base64 プレフィックスまたはアクセス可能な URL を使用し、ツール定義は現在のプロトコルに沿った形式で記述します。
チェックポイント 7：ネットワーク、プロキシ、TLS、ストリーミングのバッファリング
症状：接続タイムアウト、stream disconnected、長時間応答がない後に空の応答が返る、または非ストリーミングでは正常なのにストリーミングでは失敗する。
原因：クライアントはシステムプロキシや環境変数で設定されたプロキシを経由しているのに curl は経由していない、あるいはその逆という場合があります。企業のファイアウォール、TLS 証明書の検証、IPv6 の名前解決、DNS なども、クライアントが接続できない原因になり得ます。ストリーミングでは、一部のプロキシがレスポンスをバッファリングし、内容がすべて返ってから転送することがあります。その結果、クライアントはデータを受け取れず、タイムアウトやストリームの切断と判定します。
確認方法：まず「接続が確立していない」場合と「ストリームが途中で切れた」場合を区別します。前者では TLS エラーや接続エラーの有無を確認し、後者では通常、すでに一部の内容を受信しています。ストリーミングを無効にして再試行し、非ストリーミングで正常に動くなら、プロキシのバッファリングやタイムアウト設定に原因を絞り込めます。クライアントとターミナルのプロキシ環境変数が一致しているかも確認しましょう。
対処方法：クライアントと curl のプロキシ設定を統一します。ストリーミングリクエストでは、バッファリングを行うプロキシを経由しないようにし、クライアントのタイムアウト時間を適度に長くします。上流で断続的に接続が切れる場合は、回数を制限して再試行するか、一時的に別のモデルへ切り替えて、特定の上流だけの問題かどうかを確認できます。
API中継サービスのクイックスタート：エラーコード一覧とクライアント設定チェックリスト
エラーが発生したら、まずエラーコードで原因を絞り込み、設定チェックリストを使って項目ごとに確認しましょう。
エラーコード一覧
| エラーコード | よくある原因 | 優先して確認する項目 |
|---|---|---|
| 401 | APIキーが無効、期限切れ、または無効化されている；リクエストヘッダーの形式が不正；組織またはプロジェクトが一致しない | チェック項目 1、4 |
| 403 | APIキーは有効だが、モデル、組織、地域のポリシーによって拒否された；IPホワイトリスト；モデルが有効化されていない | チェック項目 5、アカウントの権限 |
| 404 | Base URLのパスが誤っている；エンドポイントまたはモデルIDが存在しない；ゲートウェイにそのルートが実装されていない | チェック項目 2、3、5 |
| 400 | リクエストボディ、パラメータ、モデルID、またはマルチモーダルフィールドが不正；プロバイダーのパラメータに互換性がない | チェック項目 5、6 |
| 429 | レート制限または利用枠の不足 | Retry-After を確認し、待機して再試行するか、モデルを切り替える |
| 500/502/503/529 | 上流またはゲートウェイのエラー。529は過負荷時によく発生する | 回数を制限して再試行し、ゲートウェイのログを確認する |
| タイムアウト、stream disconnected | ネットワーク、プロキシ、TLS、または上流での接続切断 | チェック項目 7 |
クライアント設定チェックリスト
| チェック項目 | 確認する内容 |
|---|---|
| 設定の参照元 | 変更したのは環境変数、設定ファイル、GUIのどれか？最も優先されるのはどれか？複数のプロファイルやプロジェクト設定による上書きはないか？ |
| Base URL | /v1 が含まれているか？クライアントが /v1 を自動で追加するか？末尾に余分なスラッシュはないか？ |
| エンドポイントの種類 | Chat Completions、Responses、Claudeネイティブ、Geminiネイティブのどれか？クライアントのバージョンは対応しているか？ |
| 認証ヘッダー | Authorization: Bearer と x-api-key のどちらか？anthropic-version は必要か？ |
| モデルID | 大文字・小文字やプレフィックスを含め、ゲートウェイのモデル一覧と完全に一致しているか？ |
| リクエストボディ | ツール、画像、reasoningパラメータが含まれているか？max_tokens フィールドは対象モデルに対応しているか？ |
| ストリーミングとネットワーク | ストリーミングは有効か？プロキシでバッファリングされていないか？クライアントとcurlのプロキシ設定は一致しているか？ |
最小限のリクエストで比較・再現する
最も効果的なのは、条件をそろえて比較する方法です。同じBase URL、同じAPIキー、同じモデル、同じリクエストボディを使い、まずcurlで送信し、次にクライアントで送信します。具体的な手順は次のとおりです。
- モデル一覧のAPIでAPIキーとBase URLを検証します。例えば、
https://api.apiyi.com/v1/modelsにリクエストを送ります； - 最小限のテキストのみのchatリクエストで、エンドポイントとモデルIDを検証します；
- ストリーミングを有効にして、ネットワークとプロキシを検証します；
- ツール呼び出しやマルチモーダルを追加して、リクエストボディを検証します；
- 各ステップで、クライアントのログとゲートウェイ側のログを両方確認します。
🚀 トラブルシューティングのヒント：APIYIのコンソールでは、利用統計と詳細な呼び出しログを確認できます。クライアントでエラーが発生したのにコンソールに今回の呼び出し記録がまったくない場合は、リクエストがゲートウェイに届いておらず、クライアントの設定またはローカルネットワークに問題があると考えられます。エラー情報を伴う記録がある場合は、ログをもとにパラメータの問題か、上流の問題かを判断できます。
よくある質問 FAQ
Q1：curl では接続できるのに、クライアントから接続できない場合、APIキーを変更すると解決しますか？
通常は解決しません。curl で接続できていれば、APIキーが有効であることは確認できています。「APIキーを変更したら直った」という場合は、変更時にクライアントを再起動したり、プロファイルを切り替えたりしたことで、設定が再読み込みされた可能性が高いです。APIキーを変更する前に、クライアントを完全に終了して再起動し、ログで実際に使われている Base URL と APIキーを確認しましょう。APIYI のコンソールでも、その APIキーの状態や呼び出し履歴を確認し、本当にキーの問題があるか調べられます。
Q2：/models エンドポイントには接続できるのに、chat リクエストが通らないのはなぜですか？
モデル一覧のエンドポイントで確認できるのは、認証と Base URL が基本的に正しいことだけです。chat エンドポイント、モデル ID、リクエストボディは検証されません。chat リクエストが通らない場合は、クライアントが使用するプロトコルとエンドポイントが一致しているか（チェックポイント 3）、モデル ID が一覧と一字一句一致しているか（チェックポイント 5）、リクエストボディに対象モデルがサポートしていないパラメータが含まれていないか（チェックポイント 6）を順に確認してください。
Q4：特定のモデルだけ失敗し、ほかのモデルは正常に動作します。まず何を確認すればよいですか？
まずモデル ID とエンドポイントを確認し、次にアカウントの権限を確認しましょう。最も多いのは、モデル ID の大文字・小文字、プレフィックス、エイリアスの違いです。次に考えられるのは、そのモデルがネイティブ形式など別のプロトコルを必要とするケースで、最後に権限や利用可否の問題を確認します。APIYI では 1 つの APIキーで複数のプロバイダーのモデルを切り替えられます。一時的に同種の別モデルで比較テストすると、特定のモデルの問題か、設定全体の問題かを素早く判断できます。
Q5：クライアントとゲートウェイのどちらに問題があるか、どう判断すればよいですか？
ポイントは、ゲートウェイ側にリクエストが届いているか、同じリクエストを curl で送ると成功するかの 2 点です。ゲートウェイに記録がなければ、基本的にクライアントかローカルネットワークの問題です。同じリクエストを curl で送ると成功し、クライアントでは失敗する場合は、URL の組み立て方やリクエストボディに問題があると考えられます。同じリクエストが curl でも失敗し、ログに 5xx が表示される場合は、ゲートウェイのサポートに問い合わせましょう。
まとめ：API中継サービスの10分間トラブルシューティングチェックリストと相談の目安
「curl では接続できるのに、クライアントからは接続できない」ときは、すぐにキーを変更せず、次のチェックリストを10分ほどで一通り確認しましょう。
- クライアントのログを確認：実際のリクエスト URL、リクエストヘッダー、リクエストボディを取得し、設定が反映されているか確認する；
- Base URL を確認：
/v1が一度だけ含まれ、二重スラッシュやパスの重複がないか確認する； - エンドポイントのプロトコルを確認：Chat Completions、Responses、Claude Messages、Gemini ネイティブのいずれかがクライアントの種類と一致しているか確認する；
- 認証ヘッダーを確認：
Authorization: Bearerまたはx-api-keyを確認し、不要な組織ヘッダーとキーの前後の空白を取り除く； - モデル ID を確認：ゲートウェイのモデル一覧と一字ずつ照合する；
- 最小構成のリクエストを送信：同じキー、同じモデル、同じリクエストボディで、curl とクライアントからそれぞれ送信して比較する；
- ストリーミングを追加：失敗した場合は、プロキシのバッファリングとタイムアウトを確認する；
- ツールまたはマルチモーダルを追加：失敗した場合は、リクエストボディのフィールドを確認する；
- 最後に判断：ゲートウェイのログをもとに、クライアント側とゲートウェイ側のどちらに問題があるか判断する。
クライアントのバグと考えられる場合：ゲートウェイ側に呼び出し記録がない場合、または curl ではまったく同じ URL、リクエストヘッダー、リクエストボディで成功するのに、クライアントでは失敗する場合です。設定が正しく、使用中のバージョンが対象のエンドポイントに対応していることも確認できたら、クライアントをアップデートするか、クライアントのプロジェクトに問題を報告しましょう。
ゲートウェイのサポートに問い合わせるべき場合：同じ最小構成のリクエストが curl でも失敗し、ゲートウェイのログに呼び出し記録が残っていて 5xx が返される場合です。また、特定のモデルでエラーが続く一方、別のモデルでは正常に動作し、モデル ID や権限にも問題がない場合も該当します。問い合わせの際にリクエスト時刻、モデル ID、エラーコード、ログのエラーメッセージを添えると、原因をより迅速に特定できます。
安定性が求められるチーム向けツールでは、複数のモデルや接続経路を用意すること自体がトラブルシューティングの手段になります。あるモデルや経路に異常が発生したとき、別のモデルに切り替えて比較テストすれば、問題の範囲をすぐに絞り込めます。APIYI apiyi.com では、1つのキーで OpenAI 互換形式と Claude、Gemini のネイティブ形式にアクセスでき、コンソールの使用量やログを使ってすばやく検証できます。価格と利用可能状況はコンソールとドキュメントをご確認ください。
著者：APIYI 技術チーム
技術交流：APIYI のウェブサイトのトップページからお気軽にお問い合わせください
