OpenAI APIを試していると、400、401、429、500などの数字と長いエラー文が表示されることがあります。数字だけを検索して修正したり、同じリクエストを何度も送り直したりすると、原因に合わない対応になりがちです。
APIエラーは、状態コード、エラー本文、request ID、発生時刻の4つへ分けると読みやすくなります。この記事では、初心者がエラー情報を安全に記録し、「入力を直す」「設定や残高を確認する」「待って再試行する」を判断する手順を解説します。
APIエラーは「原因の答え」ではなく「確認の入口」
HTTP状態コードは、失敗の大きな分類です。同じ429でも、一時的な送信量超過、利用上限、支出上限、残高不足などでは次の行動が違います。コードだけで断定せず、エラー本文のtypeやcode、メッセージを合わせて読みます。
| 見る情報 | 分かること | 記録例 |
|---|---|---|
| HTTP状態コード | 失敗の大分類 | 401、429、503 |
| エラー本文 | より具体的な理由 | invalid_api_key、slow_down |
| request ID | 問い合わせ時に対象リクエストを特定する手掛かり | req_... |
| 発生時刻 | 障害情報やログと照合する基準 | 2026-10-26 09:15 JST |
API自体の料金やChatGPTの契約との違いを先に確認したい場合は、ChatGPT APIの料金を初心者向けに解説も参照してください。
最初に作る「4点エラーカード」
修正を始める前に、次の4点を一つのメモへ残します。
状態コード：
エラー本文（秘密情報を除く）：
request ID：
発生時刻・タイムゾーン：
加えて、使ったエンドポイント、SDKと言語、同じ操作の再現性、直前の変更も記録すると切り分けやすくなります。APIキー、Authorizationヘッダー、個人情報、送信した機密データは貼り付けません。
ChatGPTでAPIエラーを読み解く5ステップ
1. 状態コードで大分類する
まず4xxか5xxかを確認します。4xxは入力・認証・権限・制限など、呼び出し側で確認できる項目が中心です。5xxはサービス側の一時的な問題を含みます。ただし、これだけで原因を確定しません。
2. エラー本文を構造ごとに読む
本文にmessage、type、code、paramがあれば、それぞれ分けます。人向けの説明だけでなく、codeの値を確認することが重要です。特に429は、送信量の制限と残高・支出上限で対処が異なります。
3. request IDと時刻を保存する
継続する問題をサポートへ伝える場合、request IDは対象リクエストを特定する助けになります。発生時刻はタイムゾーンまで残します。ログへAPIキーや本文全体を無条件に保存しないようにします。
4. 原因を3種類へ分ける
- 入力・認証：入力値、必須項目、APIキー、権限、対象IDを修正する
- 制限・残高：
error.code、利用状況、支出上限、残高、Retry-Afterを確認する - 一時障害：公式ステータスを確認し、待機後に上限回数を決めて再試行する
5. 一つだけ直して再現を確認する
複数の設定を同時に変えると、何が効いたか分かりません。入力値、認証、送信頻度などを一つずつ変更し、同じ条件で結果を確認します。コード全体の点検にはChatGPTでコードレビューする方法も使えます。
よく見る状態コードと最初の確認
| 状態コード | 大きな意味 | 最初に確認すること | 再試行 |
|---|---|---|---|
| 400 | リクエストが不正 | 必須項目、型、値、対応パラメータ | 修正後 |
| 401 | 認証できない | APIキー、余分な空白、対象Project | 原因修正後 |
| 403 | 権限がない | キーの権限、組織・Project、対象機能 | 権限確認後 |
| 404 | 対象が見つからない | エンドポイント、モデル・リソースID | 指定修正後 |
| 429 | 制限・上限・残高など | error.code、Retry-After、利用状況 |
理由による |
| 500/503 | サービス側の一時エラーを含む | 公式ステータス、request ID | 待機後に限定回数 |
この表は入口です。最新の分類と対処はOpenAI公式のエラーコードガイドを確認してください。
429はエラー本文まで読む
429を見てすぐ待機するだけでは解決しない場合があります。
slow_downなど一時的な送信量の問題：Retry-Afterがあれば従い、送信頻度を下げる- 支出上限・利用上限：設定された上限を確認する
- クレジット残高不足：残高を確認する
上限や残高の問題は、同じリクエストを送り直しても回復しません。一方、一時的なレート制限では待機と段階的な再試行が有効です。公式SDKが自動再試行する場合もあるため、アプリ側の再試行と重複して送信回数が増えないようにします。
再試行してよい場合・止める場合
待って再試行しやすい
- 500や503など一時的なサーバーエラー
Retry-Afterが示された一時的な制限- 接続タイムアウトで、処理の重複が問題にならない操作
原因を直すまで止める
- 400の入力不備
- 401の認証エラー
- 403の権限不足
- 残高不足、支出上限、利用上限
- 同じrequest ID周辺で継続し、データ重複の恐れがある処理
再試行には最大回数と待機時間を設けます。課金、ファイル作成、外部送信など副作用がある処理は、成功済みの応答を重複実行しない設計も必要です。
ChatGPTへ確認を頼むプロンプト
次のAPIエラーを、推測で断定せず初心者向けに整理してください。
1. HTTP状態コードの大分類
2. エラー本文の message / type / code / param
3. 入力・認証、制限・残高、一時障害のどれに近いか
4. 再試行前に確認する項目
5. 修正する場合は、一度に変更する項目を1つだけ提示
6. 情報不足は「要確認」と表示
状態コード：
エラー本文（APIキーや個人情報は削除済み）：
request ID：
発生時刻・タイムゾーン：
使用言語・SDK：
直前の変更：
ChatGPTの回答は説明の下書きです。実際の仕様はOpenAI公式エラーコードガイドと使用中のSDK資料で照合します。一般的な調査手順はChatGPTでエラー原因を調べる方法も参考になります。
よくある失敗
エラー全文をそのまま貼る
秘密情報や入力データが混ざる危険があります。APIキー、Authorization、Cookie、個人情報を削除し、必要なエラー項目だけを渡します。
状態コードだけで原因を決める
429のように複数の理由があるため、error.codeとメッセージまで確認します。
成功するまで無限に再試行する
負荷と費用が増え、原因も見えにくくなります。最大回数、待機、停止条件を決めます。
複数箇所を同時に変更する
再現性が失われます。一つ変更し、同じ入力で結果を記録します。
FAQ
ChatGPT Plusに入ればAPIの429は解消しますか？
ChatGPTの契約とAPIの利用枠・課金は別です。API側のerror.code、利用状況、上限、残高を確認してください。
request IDは公開してよいですか？
問い合わせの特定に役立つ情報ですが、不特定多数へ公開せず、必要なサポート先や社内担当者へ限定して共有するのが安全です。
500エラーはコードを直さなくてよいですか？
一時的なサービス側エラーを含みますが、繰り返す場合は入力、SDK、request ID、時刻を記録し、公式ステータスとサポート案内を確認します。
まとめ
APIエラーを見たら、すぐ修正や再試行を始めず、状態コード、エラー本文、request ID、発生時刻をそろえます。そのうえで、入力・認証、制限・残高、一時障害へ分ければ、次の行動を判断しやすくなります。
大切なのは、数字だけで断定しないこと、秘密情報を貼らないこと、同じエラーを無限に送らないことです。4点エラーカードを残し、一つずつ確認すれば、初心者でも再現できる調査記録になります。
コメント