0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

LLM API 4社のエラー分類マップ。同じ429でも読むキー名が違う【実装リファレンス】

0
Last updated at Posted at 2026-08-06

4社目のプロバイダを足そうとして、エラー処理のところで手が止まりました。3社ぶんの分岐がすでに並んでいて、そこに同じ形で1社ぶん足せばいいと思っていたのですが、レスポンスボディを開いたら読むべきキーの名前が違っていました。

この記事は、1社対応のコードを複数社対応に広げるときに、どこを揃えられてどこが揃わないのかを整理したものです。Claude、Gemini、OpenAI、OpenRouter の4社を1つの WordPress プラグインに同居させた実装から引いています。各社の公式仕様書ではなく、自分のコードが実際に何を見ているかの記録なので、そこは差し引いて読んでください。

検証環境:【v1.15.2 / 8月9日】

判定したい状態と、各社での来かた

アプリ側で区別したい状態は、だいたい5つに落ち着きました。認証が通っていない、レート制限に当たった、クォータが尽きた、モデル名が不正、リクエストが不正。この5つに対して、各社がどこに何を入れて返してくるかを並べます。

判定したい状態 Claude Gemini OpenAI OpenRouter
読むキー error.type error.status error.type と error.code error.code と error.message
認証NG authentication_error 401 と 403 の両方 invalid_api_key ステータスで判定
レート制限 rate_limit_error RESOURCE_EXHAUSTED 429 429(402と同扱い)
クォータ枯渇 402、message に credit / quota / billing / exceeded 402、message に quota / billing / exceeded / exhausted insufficient_quota 402、message に quota / credits
モデル不正 invalid_request_error NOT_FOUND model_not_found 上流依存で不定
リクエスト不正 invalid_request_error INVALID_ARGUMENT error.type を参照 上流依存で不定

type、status、code。同じ意味のものが3つの名前で来ます。しかも OpenRouter は上流のプロバイダによって中身が変わるので、固定値として当てにできません。ここは402と429をまとめてクォータ扱いにして、細かい区別を諦めました。

Gemini の認証まわりも揃いませんでした。キーが無効なときに401が来ることも403が来ることもあるので、この2つを同列に扱っています。片方だけ見ていると、キーの入れ間違いが「権限がない」として表示されて、利用者が設定画面のどこを直せばいいのか分からなくなります。

構造化されたキーだけで判定しきれないので、最終的にはエラーメッセージの部分一致を併用しています。stripos() で credit や quota といった単語を拾う、人間向けの文章を機械が読む形です。パースの作法としては後ろめたいのですが、4社を同じ画面の裏に置く以上、ここを捨てると分類が漏れます。文字列一致なので、各社が文面を変えたら壊れます。壊れることを承知で入れている箇所です。

Retry-After は本当に秒で来るのか

待ち時間の取り出しは、4社とも同じ1行で済ませています。

$retry_after = wp_remote_retrieve_header( $response, 'retry-after' );
if ( is_numeric( $retry_after ) && (int) $retry_after > 0 ) {
    $ex->set_retry_after( (int) $retry_after );
}

短いぶん、抜けているものが3つあります。

秒数以外の形式を捨てている

Retry-After は仕様上、秒数のほかに HTTP 日付形式も認められているはずです。日付が返ってきた場合、is_numeric() が false になるので、この分岐には入りません。例外も出ず、待ち時間が無かったことになります。

直すなら、数値でなければ日付として解釈して差分を取る、という一段を足すことになります。手元では未検証ですが、方向としてはこうです。

if ( ! is_numeric( $retry_after ) && $retry_after ) {
    $ts = strtotime( $retry_after );
    if ( $ts && $ts > time() ) {
        $retry_after = $ts - time();
    }
}

ミリ秒系の独自ヘッダを見ていない

retry-after-ms のような独自ヘッダを返すサービスがあります。標準の retry-after しか読んでいないので、そちらしか返ってこない場合は待ち時間が取れません。秒に切り上げれば使えるはずの情報を落としています。

拾えなかったことを記録していない

いちばん困るのはこれだと思っています。ヘッダが読めなかった場合、コードは静かに次へ進みます。あとからログを見ても、ヘッダが無かったのか、あったけれど形式が合わずに捨てたのかが区別できません。捨てるなら、捨てたことを残す。ここは直します。

分類したあと、何をどう分けるか

分類の結果は、リトライしていいかどうかで扱いが変わります。ステータスが429であるか、または待ち時間が0より大きければレート制限として、それ以外のクォータ系は課金側の問題として記録を分けています。待てば直るものと、こちらが何かしないと直らないものを、ログの時点で分けておくためです。

リトライの方針は、プロバイダごとに変えました。

OpenRouter の無料モデルが429を返したときは、そのモデルを10分間スロットル扱いにマークして、カタログから別の無料モデルを選び直し、その選択を設定に永続化したうえで1回だけ再送します。無料枠は落ちて当たり前という前提の作りです。有料モデルの429は、そのまま利用者に返します。

OpenAI 側は逆で、429も402もクォータ超過も、自動リトライを一切しません。自動で再送するほうが課金が伸びる分だけ害が大きいと判断したためです。同じ429に対して、片方は自動で逃がし、片方は絶対に再送しない。プロバイダの性格に合わせて態度を変えることになりました。

利用者に返すステータスは、どの分類でも一律で503にしています。サイトの訪問者に上流の事情を説明しても仕方がないので、ここは意図的に潰しました。

新しいプロバイダを足すときに確認すること

5社目を足すときに自分が見る順番です。

エラーボディのキー名

type か status か code か。ここを最初に確かめないと、あとの分岐が全部空振りします。実際にキーを間違えて叩いて、レスポンスを一度目で見るのが早いです。

401と403の使い分け

認証の失敗をどちらで返すか。両方あり得る場合は同列に扱う必要があります。

402を返すかどうか

支払い関連を402で返してくるかどうかで、クォータ判定の入口が変わります。429だけ見ていると取りこぼします。

429の中身が一種類か

分単位の超過とクォータ枯渇が同じ429に混ざっていないか。混ざっている場合、ボディを読まないと区別できません。OpenAI は別ブランチで処理しています。

メッセージの文面

部分一致で拾う単語を決めるために、実際の文面を控えておきます。credit、quota、billing、exceeded、exhausted、credits。社ごとに使う語が違います。

いま読んでいないもの

このコードは、標準の retry-after 以外のレート制限ヘッダを一切読んでいません。x-ratelimit-remaining も x-ratelimit-reset も、各社の独自ヘッダも見ていない。あと何回叩けるかを知らないまま送って、壁に当たってから対処する作りです。


ふだんはraplsworks.comで、WordPressプラグイン開発やClaude Codeまわりのことを書いています。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?