OpenAI API

冒頭まとめ 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 の記事）。 ...