OpenAI APIの429は、すべて「リクエストを少し待てば直る」エラーではありません。最初にHTTP statusだけでなく、JSON bodyのerror.type・error.code・error.messageを読みます。送信頻度の制限ならRetry-Afterとrate limit headersを見て再試行を制御します。クレジット残高やspend・usage limitなら、retryを止めて該当する組織・Project設定を確認します。
OpenAI公式のエラーガイドでは、billing系エラーは広いerror.typeがinsufficient_quotaでも、error.codeで原因を分けるよう案内しています。利用中のorganizationやProjectの状態はこの記事から確認できません。値を推測して課金・上限変更を行わず、対象Projectと権限を確認してください。
目次
まずレスポンスを安全に記録する
同じHTTP 429でも対応が異なります。再試行コードや請求設定を変える前に、失敗した一件のレスポンスと呼び出し条件を記録します。
-
HTTP statusと、JSONの
error.type・error.code・error.message -
Retry-Afterがあれば値と、x-ratelimit-…headersのlimit・remaining・reset -
endpoint、model、組織・Projectの識別情報（秘密値は除く）
-
発生時刻、request ID、同時実行数、直前の送信ペース
-
同一operationを単発で送った場合と、並列・batch処理時の差
API keyやAuthorization header、リクエスト本文に含まれる顧客データをログ・相談文へ貼らないでください。request IDやerror fieldsは、機微情報を除いたうえで管理者へ渡す診断材料になります。
error.codeで429の原因を分ける
以下はOpenAIの現行Error Codesに記載された代表的な分岐です。実際のレスポンスにあるコードを優先してください。codeが未知・空の場合、似た文字列へ無理に当てはめず、status・type・message・rate headersをそろえて確認します。
表は横にスクロールできます
| Error code / type | 主な意味 | まず行うこと |
|---|---|---|
rate_limit_exceeded またはrate limit reached | 短時間のrequest / token / model等のrate limit | Retry-Afterを尊重し、送信量と並列度を下げる |
slow_down + rate_limit_error | request rateの上昇が急すぎる場合がある | 送信速度を落とし、徐々に戻す。Retry-Afterがあれば最低待ち時間として扱う |
credit_balance_exhausted | 組織のprepaid API creditsが残っていない | 不要なretryを止め、Billing権限のある管理者が残高と購入判断を確認 |
organization_spend_limit_exceeded | 組織に設定されたhard spend limitへ到達 | 組織のLimits設定を権限者が確認する |
project_spend_limit_exceeded | 対象Projectに設定されたhard spend limitへ到達 | API keyのProjectとProject limitを照合する |
organization_usage_limit_exceeded | OpenAIが組織へ設定したusage limitへ到達 | 承認済み上限や引き上げ手順を管理者が確認する |
429 bodyのerror.typeがinsufficient_quotaでも、それだけでは「クレジットがゼロ」とは断定できません。公式ガイドは、prepaid残高、organization/project spend limit、OpenAI-assigned usage limitなどを個別のerror.codeで区別しています。たとえばcredit_balance_exhaustedなら残高、project_spend_limit_exceededならProject limitを調べます。購入や設定変更の前に、codeと管理対象が一致するかを確認してください。
一時的なrate limitなら再試行を制御する
rate limitはrequest数やtoken量などの上限で起きます。response headersが返る場合、Retry-Afterは一時的なrate-limit errorで再試行するまでの最低秒数です。x-ratelimit-limit-requests、x-ratelimit-remaining-requests、token側のlimit・remaining・reset headersも、どの資源が先に尽きたかを確認する材料になります。使えるheaderはendpointや状況により異なるため、存在しない値を仮定しないでください。
再試行は以下の順に行います。
-
Retry-Afterがある場合、その秒数より短い間隔で送らない。 -
Retry-Afterがない場合、指数バックオフと小さなランダム遅延を使う。 -
retry回数・総待ち時間に上限を設定し、同一requestを無限に送り続けない。
-
同時実行数、request/minute、token/minute、batchサイズを見直す。
-
失敗が続いたら自動retryを停止し、error codeとheaderの変化を確認する。
同じ429を連続再送しても、処理枠が早く回復するとは限りません。特に多数のworkerが同じ時間にretryすると、再び集中して制限へ達することがあります。再試行対象のAPI操作が安全か、途中まで処理された可能性があるかも確認してください。
また、slow_downは単純な固定RPM/TPM超過と同じではありません。OpenAI公式Rate Limitsは、トラフィックの増加速度が急な場合に、設定上のRPM/TPM未満でも返り得ると説明しています。rateを落として安定させ、段階的に増やしてください。厳密な適用点はmodelやtraffic条件により変わるため、普遍的な固定しきい値として扱わないでください。
credit・spend・usage limitならretryを止める
請求・残高・利用上限に関するエラーは、rate limit用のbackoffだけでは解決しません。OpenAIのエラーガイドは、billing、spend、quota系をretryしてもAPI accessは回復しないため、該当するcreditやlimitを先に確認するよう案内しています。
表は横にスクロールできます
| 管理対象 | 確認する画面・担当 | 判断時の注意 |
|---|---|---|
| Prepaid credit | Billingを管理できるorganization担当者 | credit_balance_exhaustedを確認。残高不足が判明する前に追加購入を決めない |
| Organization spend limit | OrganizationのLimits権限者 | 複数Projectへ影響する上限かを確認。必要な支出判断を経て変更 |
| Project spend limit | 対象ProjectのOwner等 | API keyがどのProjectに属するか照合してから判断 |
| Organization usage limit | Organization管理者 | spend capとは別の、割当済みusage limitかを確認 |
| Rate limit | APIを呼ぶチーム / 開発担当 | RPM・TPM・model・endpoint・同時送信を確認し、送信制御を調整 |
Hard spend limitはAPI requestを止める制御ですが、支出alertと同じではありません。OpenAIの公式Rate Limitsは、alertは通知でrequestを止めず、hard spend limitは該当requestに429を返すと説明しています。Billingの通知を受け取っただけでspend capに到達したと判断せず、正確なerror codeと設定を見ます。
Spend limitの変更には組織・Project設定への権限が必要な場合があります。権限がなければ自分で課金・上限変更せず、error code、時刻、request ID、対象Projectを管理者へ渡します。上限の変更や追加購入はコストを変える判断なので、単なるrate retryの修正に混ぜないでください。
429以外の応答を429とまとめない
エラー処理ではstatusとcodeの組み合わせを読みます。公式のrate-limit guideは、急なrate増加を示すslow_downは429、model overloadを示すserver_is_overloadedは503として区別する案内をしています。Retry-Afterは一時的な429や503で返る場合がありますが、billing・quotaの回復を意味しません。
Streaming requestでは、開始前のHTTP error responseと、stream開始後に送られるerror eventを区別します。出力を受信した後、処理全体を安全性確認なしに同じrequestとして再実行すると、重複処理や費用につながる場合があります。どのendpointを使っているかに合わせ、公式APIリファレンスのresponse形式を確認してください。
SDKが自動retryする場合もあります。アプリ側で独自retryを加える前に、SDK設定と最大試行回数を確認し、二重retryや過剰送信を避けます。
診断の具体例
たとえばログにHTTP 429、error.type: insufficient_quota、error.code: project_spend_limit_exceededが記録されていたとします。この場合は、一時的なrequest rate超過として同じrequestを繰り返すのではなく、API keyが属するProjectとProjectのspend controlを管理者に確認します。Retry-Afterが仮にあっても、spend limitが主因なら待機だけで解決するとは限りません。
別の例として、429でerror.code: slow_down、error.type: rate_limit_errorが返り、呼び出しを短時間に急増させたなら、同時実行を絞り、Retry-Afterを待ってから小さく再試験します。これは請求設定を変える根拠ではありません。いずれも例示であり、実際のresponseを見ずに原因を決めつけないでください。
解消後の再開条件
修正後は一度に処理量を元へ戻さず、対象Project・model・endpoint・送信率を記録したうえで少量から試します。rate limitならheadersと次のresponseを、billing・spend・usage limitなら権限者が変更内容と反映状態を確認します。
再開前の短いチェックリスト：
-
最後のerror bodyから
type / codeを分類した -
rate-limitなら
Retry-Afterとremaining/reset headersを確認した -
billing系ならcredit・organization spend・project spend・usage limitを分けた
-
不要な自動retryや多重retryを止めた
-
管理者に渡す記録からAPI key・Authorization header・顧客データを除いた
-
最初の再試験を低い送信率で行い、結果とrequest IDを記録した
次にすること： まず429 response bodyのerror.codeを読み、rate系なら送信を抑えてRetry-Afterを尊重し、credit/spend/usage系ならretryを止めて該当範囲の管理者へ確認を依頼します。原因が判明する前の追加購入や上限変更は行わないでください。
参考資料
Evidence checked: 2026-10-15. No organization, Project, billing page, or API logs were accessed; examples are based on current official documentation.