Codexの失敗は、次のような行で終わることがあります。
textexceeded retry limit, last status: 429 Too Many Requests stream disconnected before completion exceeded retry limit, last status: 401 Unauthorized
これらは同じ原因を示していません。401は、あるリクエスト経路が認証を拒否した状態です。429は、どこかのサービスがリクエスト頻度、残高、支出、利用量の境界を適用した状態です。stream disconnectedは応答が完了する前に流れが切れたことだけを示します。exceeded retry limitはクライアントが再試行を終えた理由であり、別のquotaではありません。
認証ファイルの削除、keyの再発行、timeoutの延長、大きなタスクの連打をする前に、実際の経路と最初の有効なエラーを固定します。
状態を変える前の確認
CLIでは、まずread-onlyの2コマンドを実行します。
bashcodex --version codex login status
エラー全文、発生時刻とタイムゾーン、Codexの画面、モデル、表示されたrequest IDも記録します。codex login statusは認証方式を確認するもので、下流のすべての権限が有効だと証明するものではありません。custom providerを使う場合は、credentialを表示せずに、実際に有効なproviderとbase URLも確認します。
Codex App Serverの公式エラー分類では、Unauthorized、上流のHTTP失敗、ResponseStreamConnectionFailed、ResponseStreamDisconnected、ResponseTooManyFailedAttemptsが別の種類です。上流HTTP statusが分かる場合は、httpStatusCodeとして別に渡されます。画面に最後の一行しか出なくても、この区別を保つことが重要です。
どの経路がエラーを所有しているか
| 利用経路 | 確認する証拠 | 代用できない情報 |
|---|---|---|
| ChatGPTでsign inしたCodex | 現在のaccount/workspace、Codex usage、新規sessionでの再現 | Platform APIの残高やRPM/TPM |
| OpenAI API key | structured error、organization/project、billing、limits、response header | ChatGPT Plus/Proの状態 |
| 外部provider/gateway | 有効なendpoint、provider account、gateway/upstream log、trace ID | 関係のないOpenAI dashboard |
失敗したリクエストを処理していないaccountの「残量あり」は、正しくても診断には使えません。認証方式、provider、確認している管理画面が同じ経路に属することを先に確かめます。
401は再試行ではなく認証の判断
OpenAI Platform APIの401には、invalid authentication、誤ったAPI key、organization membership不足、IP allowlist不一致があります。公式API error一覧で具体的なerror.codeを確認し、同じorganization/projectを見ているか照合します。
ChatGPT loginの場合、codex login statusが想定した方式かを確認します。保存済みsessionが無効、または別accountだと確認できたときに再認証します。codex logoutは保存credentialを消す操作なので、最初の診断コマンドにはしません。公式authガイドでは、process environmentが管理するworkload identityはlogin/logoutと挙動が異なることも示されています。
API keyの場合、実行processのkeyが、確認中のendpoint・project・organization・IP policyと一致するか確認します。key、environment全体、auth.jsonを公開しないでください。invalid_api_keyやmembership、IP authorizationを修正した後に、短いrequestを一度だけ実行します。状態が変わらない安定した401にbackoffは不要です。
外部gatewayでは、入口のcredentialを拒否した401と、gatewayが上流から受け取った401を分けます。request IDと同時刻のlogを対応させ、どのhopで拒否されたか確認します。
429は具体的なownerを読んでから待つ
OpenAI Platform APIの429はrequest rateだけではありません。現在の公式error guideは、credit balance、organization/project spend limit、organization usage limitも区別しています。billing・spend・quotaは、繰り返すだけでは回復しません。
- 有効な
Retry-Afterまたはrequest-rate codeがある：同時実行を下げ、指定時間以上待ち、有限回だけ試す。 credit_balance_exhausted：対象organizationのbalanceが変わるまで再試行しない。- spend limit：実際のrequestを送ったproject/organizationを確認する。
- ChatGPT/Codexのusage window：そのaccount画面に表示された回復条件に従う。
- 外部providerの429：そのproviderのbilling、quota、concurrency、logを確認する。
- 最後の429行しかない：時刻、route、request IDを保存し、固定の待ち時間を推測しない。
短い直列requestは成功し、並列taskだけ失敗するなら、concurrencyを下げて境界を記録します。ただし、それだけで最終的な原因は決まりません。負荷を下げても不規則なら、試行を止めてgateway/provider logに戻ります。
Stream disconnectedは切れた段階を比べる
response streamはclient、proxy/TLS inspection、管理network、gateway、upstream service、端末のnetwork切替で中断する可能性があります。メッセージだけでVPNやOpenAI outageを断定できません。
一度の小さな比較で範囲を絞ります。
- 同じaccount、provider、modelで新しいsessionを作り、機密情報を含まない短いrequestを送る。
- 出力前、部分出力後、明示的なHTTP statusのどこで失敗したか記録する。
- policyが許す場合だけ、別の信頼できるnetworkで同じrequestを一度試す。
- 失敗時刻とrequest IDをgateway/provider logに対応させる。
- 特定client/versionだけなら差分を記録し、複数の変数を同時に変更しない。
別networkで成功しても、組織のsecurity controlを無効化してよいという意味ではありません。両方で同時に失敗する場合は、account、provider、gateway、現在のservice evidenceを優先します。
stream_idle_timeout_msをすぐ増やさないでください。timeoutはclientが待つ時間を変えるだけで、誤ったbase URL、401、残高不足、gatewayによる意図的な切断を直せません。
Retry設定は上流の状態を変えない
Codexにはrequest retries、stream retries、stream idle timeoutの設定があります。公式config referenceは、model_providersなどのprovider/auth keyがuser-level設定であり、project-local .codex/config.tomlでは無視されることも説明しています。
回数を増やすと、確実に失敗する時間を延ばし、gateway側のretryと重なってrequestを増やし、最初の有用なerrorを隠すことがあります。変更するのは、一時的なrate/transport conditionと再試行可能性が確認でき、attempt数と総時間に上限を置ける場合だけです。
Supportに渡す最小情報
短いrequestが新規sessionでも失敗する、account状態とerrorが矛盾する、特定version/providerだけで再現する場合は、次をまとめます。
- Codex version、CLI/App/IDE、OS
- auth methodとprovider名（credentialなし）
- 最初と最後の失敗時刻、time zone
- 出力前か部分出力後か
- error category、HTTP status、
error.code、request ID - 単一session/modelか、複数でも起きるか
- 一度だけ行った比較テストと結果
- 最初の失敗を残す最小のredacted log
API key、token、authorization header、完全なauth/config、environment dump、private promptやsource codeは送らないでください。
復旧の判定は元の経路で行います。同じaccount、provider、clientの短いrequestが完了し、最初のerrorが再発しないことを確認します。account、model、networkを変えた成功は回避策として有用ですが、元の経路が直った証拠ではありません。
