Posts

冒頭まとめ OpenAI API の 400 Bad Request は、送った要求の内容が受け付けられなかったことを示します。公式の説明では、要求の形式が壊れているか、必須のパラメータが欠けている場合とされ、エラー文言がどこが問題かを教えてくれるはずだと書かれています。 実際、応答には機械が読める形で場所と種類が入ります。param に問題のあるパラメータの名前、code に種類の識別子です。この2つを読めば、直す場所と直し方がほぼ決まります。 よく見る code は3つです。unsupported_parameter は、そのパラメータ自体がそのモデルでは使えない、という意味です。unsupported_value は、パラメータは使えるがその値が使えない、という意味です。context_length_exceeded は、入力と出力の合計が上限を超えた場合です。 もう1つ、境界として押さえておくべき点があります。モデル名の誤りは 400 ではありません。存在しないモデルや権限の無いモデルを指定した場合、返るのは 404 で、code は model_not_found です。400 の原因としてモデル名を探し始めると遠回りになります。 エラーの概要 最も多く見る形は、使えないパラメータを送った場合です。 { "error": { "message": "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.", "type": "invalid_request_error", "param": "max_tokens", "code": "unsupported_parameter" } } param に max_tokens と名指しされ、message には代わりに使うべき名前まで書かれています。推測の余地がありません。 値だけが問題の場合は、code が変わります。 { "error": { "message": "Unsupported value: 'temperature' does not support 0.7 with this model. Only the default (1) value is supported.", "type": "invalid_request_error", "param": "temperature", "code": "unsupported_value" } } 上限超過の場合は、内訳まで示されます。 ...

冒頭まとめ OpenAI API の 401 は、認証に失敗したことを示します。ただし「キーが間違っている」だけを意味するわけではありません。 公式のエラー一覧を見ると、401 は4種類に分けて説明されています。認証情報が無効な場合、送ったキーが正しくない場合、アカウントが組織に所属していない場合、そして要求元の IP が許可リストに一致しない場合です。 重要なのは、このうち3つはキーを作り直しても直らないことです。認証情報が無効な場合の説明には、失効したキーを使っている、要求先の組織やプロジェクトに割り当てられたものとは別のキーを使っている、そして呼び出しているエンドポイントに必要な権限をキーが持っていない、という3つの原因が挙げられています。キーそのものは有効でも、宛先や権限が合っていなければ 401 です。 もう1つ、切り分けを一気に進める性質があります。「Incorrect API key provided」の文言には、実際に送られたキーが伏字付きで入ります。これを自分のキーと突き合わせて、一致しないなら、調べるべきはキーではなくそのキーを送っている場所です。 したがって最初にやることは、文言がどの種類かを見分けることです。 エラーの概要 キーが正しくない場合の応答は、この形になります。 { "error": { "message": "Incorrect API key provided: sk-Eyftb***************************************99vW. You can find your API key at https://platform.openai.com/account/api-keys.", "type": "invalid_request_error", "param": null, "code": "invalid_api_key" } } message の中の伏字部分に注目してください。先頭と末尾の数文字が見えています。**これはサーバーが受け取ったキー**なので、自分が設定したつもりのキーと照合できます。 プログラムから呼んでいる場合、公式のソフトウェア開発キットでは AuthenticationError として現れます。公式の説明は、キーまたはトークンが無効・期限切れ・失効している、というものです。 文言は主に次の4種類に分かれます。この判別が切り分けの起点になります。 Invalid Authentication → 宛先か権限の不一致 Incorrect API key provided: sk-... → 送られたキーそのものが違う You must be a member of an organization to use the API → 組織への所属が無い IP not authorized → 許可リストとの不一致 まず最初に：文言を4つに振り分ける 第一に、文言に伏字のキーが含まれているかを見ます。含まれていれば、それが実際に送られたキーです。 ...

冒頭まとめ OpenAI API の 403 は、公式のエラー一覧では1項目しか定義されていません。国・地域・領域が対応外である、というものです。 このエラーには、他と違う特徴があります。応答の type が invalid_request_error ではなく request_forbidden になります。code は unsupported_country_region_territory です。この2語が見えた時点で、系統が確定します。 そして最も重要な点です。判定されているのは利用者の所在地ではなく、要求の送信元 IP アドレスがどこと判定されたかです。対応国にいても、経路の途中で別の地域と判定されれば 403 になります。実際、提供元の窓口も利用者に対し、IP アドレスを教えてほしい、正しくない地域に判定されていないか確認する、と応じています。 もう1つ、プログラムから呼んだ場合の 403 として、資源へのアクセス権が無い場合があります。公式のソフトウェア開発キットでは、要求した資源へのアクセス権が無い状態として定義され、正しいキー・組織 ID・資源 ID を使っているか確認するよう案内されています。 逆に、403 だと思われがちだが違うものがあります。残高や利用額の上限は 429、モデルへのアクセス権は 404、キーの失効や組織の不一致は 401 です。いずれも 403 では返りません。 エラーの概要 地域の非対応は、次の形で返ります。 { "error": { "code": "unsupported_country_region_territory", "message": "Country, region, or territory not supported", "param": null, "type": "request_forbidden" } } 他のエラーと並べると違いが際立ちます。400 や 401 の type は invalid_request_error ですが、こちらは request_forbidden です。type を見るだけで、内容の問題でも認証の問題でもないと分かります。 もう1つ確認すべきことがあります。応答が JSON かどうかです。上の形が返っていれば、API の層が判断した結果です。JSON ではなく HTML の遮断画面が返っている場合、判断したのは API の層ではなく、その手前にある仕組みです。調べる先が変わるため、本文の形式を最初に確認してください。 まず最初に：type と送信元 IP を確認する 第一に、type を読みます。request_forbidden であれば地域の系統です。 ...

冒頭まとめ OpenAI API の 404 は、指定した対象が見つからないことを示します。ただし「何が」見つからないかで、3つの系統に分かれます。 1つ目は**モデルです。code は model_not_found、文言は指定したモデルが存在しないか、アクセス権が無い**、という形になります。 2つ目は経路です。文言は Invalid URL (POST /v1/...) の形で、code は付きません。要求を送った先の経路そのものが存在しない場合です。 3つ目は資源の識別子です。ファイルやアシスタントなど、識別子で指定する対象が見つからない場合が該当します。 この3つには共通の性質があります。文言に、実際に要求された内容がそのまま入ることです。モデル名なら送られたモデル名、経路なら送られた経路。したがって、自分が指定したつもりの値と突き合わせるだけで、原因の大半は確定します。 そしてもう1つ、押さえるべき点があります。モデルの文言は、存在しないのか、権限が無いのかを区別しません。1つの文に両方が併記されています。したがって「モデル名が正しいか」だけを確認しても、原因の半分しか潰せません。 エラーの概要 モデルが見つからない場合の応答です。 { "error": { "message": "The model `gpt-4` does not exist or you do not have access to it.", "type": "invalid_request_error", "param": null, "code": "model_not_found" } } param は null です。どのパラメータが問題かは示されません。示されるのはモデル名そのもので、文言の中に埋め込まれています。 経路が違う場合は、形式がまったく変わります。 404 Invalid URL (POST /v1/chat/completions/) 括弧の中に、実際に要求されたメソッドと経路が入ります。上の例では末尾に余分な区切り文字が付いています。これが原因そのものです。 同じ形で、次のような経路も報告されています。 404 Invalid URL (POST /v1/v1/chat/completions) 404 Invalid URL (POST /v1/chat/completions/chat/completions/) いずれも、基点となる URL と経路の組み立てが二重になった結果です。文言を読めば、何が起きたかがそのまま見えます。 まず最初に：文言に入っている値を自分の指定と突き合わせる 第一に、code があるかを見ます。model_not_found ならモデルの系統、無ければ経路か資源の系統です。 ...

冒頭まとめ OpenAI API の 422 には、他のコードと違う特殊な事情があります。公式の API エラー一覧に、422 の項目がありません。401、403、404、429、500、503 には説明がありますが、422 は載っていません。 定義があるのは、公式のソフトウェア開発キット側です。ライブラリのエラー区分の表に UnprocessableEntityError があり、説明は「形式は正しいにもかかわらず要求を処理できなかった」、対処は「もう一度試すこと」となっています。状態コードの対応表でも 422 はこの区分に割り当てられています。 つまり 422 は、API 側のエラーとしてではなく、クライアント側の受け取り方として定義されているわけです。 これが実務で意味を持ちます。開発キットは、接続先が OpenAI 本体かどうかに関係なく、422 を受け取れば同じ例外を投げます。そして OpenAI 互換をうたうサーバーの多くは、入力の検証に失敗したとき 422 を返します。 したがって、422 を見たときに最初に疑うべきは、自分の要求内容ではなく接続先です。応答本文の形を見れば、どちらが返したかはすぐに分かります。 エラーの概要 OpenAI 本体のエラー応答は、常にこの構造です。 { "error": { "message": "...", "type": "invalid_request_error", "param": "messages", "code": "..." } } 一方、422 を返す互換サーバーの多くは、次の構造を返します。 { "detail": [ { "type": "string_type", "loc": ["body", "input", "str"], "msg": "Input should be a valid string", "input": [[2149, 87515, 1764, 374]], "url": "https://errors.pydantic.dev/2.5/v/string_type" } ] } error オブジェクトではなく detail 配列です。項目の名前もまったく違います。これは、多くの互換サーバーが特定のフレームワークの上に作られており、その検証機構がこの形式でエラーを返すためです。末尾に検証ライブラリの説明への URL が入る点も特徴的です。 紛らわしいのは、どちらの場合も開発キットの例外名は同じになることです。UnprocessableEntityError という名前を見て「OpenAI が返した」と判断してはいけません。 ...

冒頭まとめ OpenAI API の 429 Too Many Requests は、1つの意味を持つエラーではありません。性質のまったく違う2種類が、同じ状態コードで返ります。 1つ目はレート制限の超過です。応答の type は rate_limit_exceeded で、こちらは待てば通ります。 2つ目はクォータの不足です。type は insufficient_quota、文言は現在のクォータを超過したので契約と請求の設定を確認せよ、という趣旨になります。こちらは待っても永久に直りません。原因が送信の速さではなく、残高や請求の状態にあるためです。 公式文書はこの区別を明示しています。Retry-After ヘッダーは一時的なレート制限による 429 に付くことがあるが、クォータや請求など利用者側の対応が必要なエラーが再試行で解決することを意味しない、と書かれています。再試行の節にも、そうしたエラーは再試行するなと明記されています。 やっかいなのは、この2つをプログラムが区別しない点です。公式のソフトウェア開発キットは、429 を含む一部のエラーを既定で2回自動的に再試行します。つまりクォータ不足でも黙って3回投げられ、遅くなるだけで結果は変わりません。 したがって最初にやることは決まっています。応答の type を読むことです。 エラーの概要 レート制限の超過はこの形です。 { "error": { "message": "Rate limit reached for gpt-4o-mini in organization org-xxx on tokens per min (TPM): Limit 200000, Used 199200, Requested 1200.", "type": "rate_limit_exceeded", "param": null, "code": "rate_limit_exceeded" } } クォータ不足は、同じ 429 でも中身が違います。 { "error": { "message": "You exceeded your current quota, please check your plan and billing details.", "type": "insufficient_quota", "param": null, "code": "insufficient_quota" } } 判定は type の1語で終わります。文言の「quota」という単語に引きずられないでください。レート制限側の文言にも上限の話は出てきます。 ...

冒頭まとめ OpenAI API の 500 は、公式のエラー一覧で提供側の問題と明記されています。文言は要求の処理中にサーバー側で問題が起きた、という趣旨で、示されている対処は「短い待機のうえで再試行し、続く場合は問い合わせる」ことです。あわせて稼働状況の確認も案内されています。 つまり、送った内容を直しても直りません。400 番台とは調べる方向が正反対です。 そのうえで、実務的に最初に確認すべきことがあります。何回送られたかです。公式のソフトウェア開発キットは、接続の問題、408、409、429、そして 500 番台を既定で2回自動的に再試行します。したがって、手元のログに1回しか記録されていなくても、実際には3回送られたうえで諦めた状態です。 この前提を知らないと、対処を二重に積むことになります。自作の再試行を足せば、待ち時間も送信回数も掛け算で増えます。 なお、code が null で type が server_error の形が典型ですが、応答が JSON ですらない場合もあります。その場合は API の層が返したものではありません。 エラーの概要 典型的な応答です。 { "error": { "message": "The server had an error while processing your request. Sorry about that!", "type": "server_error", "param": null, "code": null } } param も code も null です。指し示せる場所が無いということで、これ自体が「利用者側の問題ではない」ことの表れです。400 番台では param や code に手がかりが入るのと対照的です。 開発キットからは InternalServerError として現れます。公式の対応表では、状態コードが 500 以上のものがこの区分にまとめられています。 一方、サーバーから応答が返る前に失敗した場合は、区分自体が変わります。接続できなかった場合と時間切れの場合は、状態コードを持たない別の区分です。500 が返っているなら、少なくとも要求は届いています。 まず最初に：本当に 500 か、何回送られたかを確定する 第一に、本文が JSON かを見ます。HTML が返っていれば API の層ではなく前段の仕組みが返しています。 ...

冒頭まとめ OpenAI API の 502 には、他のエラーと決定的に違う点があります。公式のエラー一覧に載っていないことです。400、401、403、429、500、503 は項目として説明がありますが、502 はありません。 理由は応答を見れば分かります。502 のときに返るのは JSON ではなく、次のような HTML です。 <html> <head><title>502 Bad Gateway</title></head> <body> <center><h1>502 Bad Gateway</h1></center> <hr><center>cloudflare</center> </body> </html> 末尾に、前段で配信を担う事業者の名前が入っています。つまりこの応答を作ったのは API の層ではありません。要求は API に届く前に遮られています。 この違いは対処に直結します。type も code も param も存在しないため、応答から原因を読み取る通常の手順が使えません。代わりに確認するのは、本文が JSON かどうか、そして何が起きたときに出るかです。 さらに注意すべき点があります。502 は、その裏にある本当の失敗を覆い隠すことがあります。実際に、認証の失敗が 502 として現れた事例が報告されています。 エラーの概要 通常のエラーと並べると、構造の違いが際立ちます。 # 400 や 429 の場合（API の層が返す） {"error": {"message": "...", "type": "...", "param": null, "code": "..."}} # 502 の場合（前段が返す） <html><head><title>502 Bad Gateway</title></head> ... <center>cloudflare</center> ... プログラム側では、この違いが例外の形にも現れます。本文を JSON として解釈しようとして失敗する、あるいは中身の無いエラーとして扱われる、といった形です。公式のソフトウェア開発キットでは 500 番台としてまとめて扱われるため、500 と 502 が同じ区分に見えてしまう点にも注意が要ります。 ...

冒頭まとめ OpenAI API の 503 は、公式のエラー一覧で混雑として定義されています。文言は現在処理系が過負荷なので後で試すよう促す趣旨で、原因はサーバー側が大量の通信を受けていること、対処は短い待機のうえでの再試行、と明記されています。 つまり、送った内容にも、自分の設定にも問題はありません。全利用者に対して起きている状態です。 ただし、ここに落とし穴があります。同じ「過負荷」の文言は 429 でも返ります。公式の説明資料には、この文言が 429 の項目としても掲載されています。文言だけを読んで「混雑だから待とう」と判断すると、実際には自分の上限に達していた、という取り違えが起こります。 この2つは対処が違います。503 は待てば通ります。429 は、レート制限なら待って通り、クォータ不足なら待っても永久に通りません。 したがって、文言ではなく状態コードを見るのが出発点になります。 エラーの概要 応答は次の形です。 { "error": { "message": "The engine is currently overloaded, please try again later", "type": "server_error", "param": null, "code": null } } param も code も null です。500 と同じ構造で、指し示せる場所が無いことを示しています。 公式のソフトウェア開発キットでは、状態コードが 500 以上のものがまとめて1つの区分になります。したがって、開発キットの例外の型だけでは 500 と 503 を区別できません。状態コードを取り出して確認する必要があります。 再試行については、開発キットが接続の問題、408、409、429、そして 500 番台を既定で2回自動的に再試行します。503 もこの対象です。手元の記録に1回しか出ていなくても、実際は3回試したうえで諦めた状態です。 まず最初に：状態コードで 429 と分ける 第一に、状態コードを確認します。文言が「過負荷」でも、503 と 429 では意味が違います。 第二に、429 だった場合は type を読みます。rate_limit_exceeded なら待てば通り、insufficient_quota なら待っても通りません（OpenAI API の 429 の記事）。 ...

冒頭まとめ Azure で 502 Bad Gateway を受け取る場面は、Application Gateway を前段に置いた構成に集中します。表示される文言も定型で、要求を取り次いだ側が背後から正しい応答を得られなかった、という趣旨のものです。 公式のトラブルシューティング文書は、このエラーの原因を明確に列挙しています。ネットワークの遮断規則・利用者定義の経路・独自の名前解決による遮断、既定の正常性確認が背後に届かないこと、独自の正常性確認の設定不備、背後の一覧が未設定または空であること、一覧の中に正常な相手が1つも無いこと、要求の時間切れや接続の問題、そして背後の証明書が一致しないことです。 並べてみると、多くが1点に帰着します。背後が正常だと判定されていない、ということです。同じ文書には、一覧内のすべてが正常でないと判定された場合、要求は転送されず 502 が返る、と明記されています。したがって調査の起点は、設定ファイルではなく背後の正常性の状態です。 もう1つ、時間に関する記述があります。要求を受け取った Application Gateway は、背後からの応答を一定時間待ちます。既定は20秒です。そして「v1 では、この時間内に応答が返らないと利用者は 502 を受け取る」と、版を明示したうえで書かれています。版を明示しているということは、別の版では同じ状況が同じ結果にならない可能性がある、ということです。自分の環境がどちらの版かを先に確認してください。 エラーの概要 利用者側には定型の文言が表示されます。応答が無効だった、という趣旨のものです。 Server Error: 502 - Web server received an invalid response while acting as a gateway or proxy server. 判断の材料は、この画面ではなく背後の正常性の状態です。公式文書には、一覧内のすべてが正常でないと判定された場合に 502 が返ることと、詳細を示す欄に表示される内容から調査を始めるべきことが書かれています。 正常性の確認の既定の挙動も定義されています。確認の要求は <プロトコル>://127.0.0.1:<番号> の形で送られ、番号とプロトコルは設定から引き継がれます。そして、正常と見なされる応答は 200 から 399 までの状態コードだけです。この範囲外を返すパスを確認先にしていると、背後が正しく動いていても正常でないと判定されます。 まず最初に：背後の正常性を見る 第一に、背後の正常性の状態を確認します。すべてが正常でないと判定されていれば、原因はそこにあります。アプリケーションの中身を調べる前に、判定が通るようにしてください。 第二に、詳細を示す欄の内容を読みます。公式文書には、接続を確立できない場合の文言として、確認に使う番号で背後が応答しているかを確かめること、そして遮断の設定が邪魔していないかを確かめることが挙げられています。 第三に、正常と判定されているのに 502 が出る場合を分けて考えます。この場合、判定は通っているので、疑うのは実際の通信の側です。証明書の不一致や、名前の扱いの食い違いが候補になります。 よくある原因と解決手順 原因1：遮断の設定で、確認の通信が届いていない 公式文書が最初に挙げている原因です。ネットワークの遮断規則、利用者定義の経路、独自の名前解決のいずれかが、Application Gateway から背後への到達を妨げていると、正常性の確認が失敗し、結果として 502 になります。 同じ文書には、これらの設定が Application Gateway 側の区画にある場合と、背後の機器がある区画にある場合の両方がありうる、と書かれています。片方だけを見て安心しないでください。 さらに、管理用の通信に必要な範囲も決まっています。公式の正常性に関する文書によれば、v1 では 65503 から 65534、v2 では 65200 から 65535 への受信を許可しておく必要があります。この範囲を塞ぐと、背後の設定が正しくても機能しません。 ...