著者注：モデル API のエラーをエラーコード別に分類し、再試行する場合、代替モデルに切り替える場合、処理を止めて設定を修正する場合を解説します。エラーコードの分類表、代替モデルの確認表、リリース前チェックリストも掲載しています。
モデル API でエラーが発生したら、まずエラーの種類を確認し、それに応じて対処しましょう。4xx はリクエストや設定に問題がある場合が多く、再試行しても改善しません。5xx、529、タイムアウトは回数を制限して再試行し、それでも失敗したら代替モデルへの切り替えを検討します。べき等性が保証されていないリクエストは、自動で再試行しないでください。再試行を標準の対処法にしてはいけませんし、切り替えですべての問題が解決するわけでもありません。本番環境の障害は、モデル自体の停止ではなく、エラー処理のロジックが小さな不具合を増幅し、二重課金やデータベースへの重複書き込み、処理全体へのレート制限を招くことで起きることも少なくありません。
この記事はエラーコード辞典の翻訳ではありません。モデル API を本番環境またはそれに近い環境に組み込んでいる開発者に向けて、エラー発生時に状況を悪化させないための対応を解説します。エラーコードの分類表、再試行とフォールバックの戦略、代替モデルの機能確認表、そしてそのまま使えるリリース前チェックリストを紹介します。要点を一言でまとめると、4xx はまず修正、5xx は再試行を検討、非べき等なリクエストはまず手を止める、です。
モデル API エラーを5種類に分類：原因を見極めてからリトライか切り替えを判断する
結論から言うと、モデル API のエラーは5種類に分けられ、それぞれ対処の方向性はほぼ決まっています。まずエラーコードを分類すれば、その後のリトライや切り替えの判断に迷いにくくなります。
| エラーの種類 | 代表的なステータスコード | 原因の所在 | 基本の対応 |
|---|---|---|---|
| リクエストエラー | 400、404、409、422 |
リクエストボディ、パラメータ、モデル ID、エンドポイント | リトライせず、リクエストを修正 |
| 認証・認可エラー | 401、403 |
キー、リクエストヘッダー、権限、地域またはポリシー | リトライせず、キーと権限を確認 |
| 利用枠不足・レート制限 | 402、429 |
残高、同時実行数、リクエスト頻度、モデルの利用枠 | 402 は停止；429 はエラーボディを確認してから待機時間を延ばすか切り替え |
| 上流側の障害 | 500、502、503、529 |
ゲートウェイ、上流サービス、過負荷 | 回数を限定してリトライし、失敗したら切り替え |
| タイムアウト・ストリーム中断 | 408、504、ネットワークタイムアウト、ストリーム切断 |
通信経路、長い出力、上流の応答遅延 | 実行・課金済みかを確認し、冪等な場合のみリトライ |
5種類のエラー分類のポイント：「リトライ」と「切り替え」を区別する
リトライとは、同じモデル、同じ経路でもう一度リクエストを送ることです。一時的な不安定さへの対処に適しています。一方、切り替えとは、モデルや経路を変更することです。特定の上流サービスが継続して利用できない場合に適しています。両者のコストも異なります。リトライでは遅延や二重課金が発生する可能性があり、切り替えでは出力品質、ツール呼び出しの互換性、費用が変わる可能性があります。
そのため、判断は次の3段階で進めます。まずエラーの種類を確認し、次にリクエストが冪等かどうかを判断し、最後にリトライ、切り替え、停止のいずれかを選びます。2段階目を飛ばすのは特に危険です。すでに実行されたツール呼び出しを再実行すると、単に「費用が余分にかかる」だけでは済まないこともあります。
なぜ「すべてリトライ」するとモデルAPIのエラーが深刻になるのか
結論から言うと、すべてのエラーを一律にリトライする方法は、一見安全に思えますが、実際にはコスト、副作用、レート制限を同時に悪化させます。本番環境では、こうしたロジックが引き起こす障害のほうが、元のエラーよりも原因を調べにくいことが少なくありません。
1つ目の問題は、二重課金です。ストリーミング応答が中断しても、リクエストが失敗したとは限りません。上流ですでに一部のトークンが生成され、その分の料金が発生している可能性があります。むやみに再実行すると、同じタスクに2回分の料金を払うことになり、特に出力の長いタスクで影響が大きくなります。
2つ目の問題は、処理の重複実行です。エージェントを使う場面では、1回のモデルリクエストをきっかけに、データベースへの書き込み、メッセージの送信、タスクの作成、さらには決済が行われることがあります。ツール呼び出しの段階でタイムアウトした場合、ツールがすでに実行されたかどうかは分かりません。そのままリクエスト全体を再実行すると、注文やメールが重複する可能性があります。
3つ目の問題は、レート制限のさらなる悪化です。429 は、上流からの「ペースを落としてほしい」というシグナルです。このとき、クライアントがすぐに並列でリトライすると、自ら負荷を増やすことになります。さらによくある悪い例が、すべての4xxエラーをリトライするケースです。もともとはキーの入力ミスによる 401 だったのに、何度もリトライした結果、リクエスト数が上限に達し、ログには大量の 429 が記録されます。その結果、本当の原因が隠れてしまいます。
401、429、500、529 エラーコードの対応表：リトライすべきか、切り替えるべきか
結論から言うと、下表にまとめた本番環境でよく見られる14のステータスコードのうち、リトライする価値があるのは一部だけです。切り替えは、リトライが無効だと確認できた場合に検討します。表の「切り替え」は予備のモデルや経路への変更を指します。具体的な判断は、実際のエラーボディと各社のドキュメントを確認してください。
| ステータスコード | 主な意味 | リトライ | 切り替え | 対応 |
|---|---|---|---|---|
400 |
リクエスト形式またはパラメータの誤り | しない | しない | リクエストボディを修正し、フィールドと型を確認 |
401 |
キーが無効、または認証失敗 | しない | しない | キー、Authorization リクエストヘッダー、Base URLを確認 |
402 |
残高不足またはクォータの使い切り | しない | 状況に応じて経路を変更 | チャージするか、クォータのある経路に切り替え、アラートを出す |
403 |
権限、地域、またはポリシーによる拒否 | しない | しない | アカウントの権限、モデルの利用権限、地域制限を確認 |
404 |
モデルまたはエンドポイントが存在しない | しない | しない | モデルIDとエンドポイントのパスを確認 |
408 |
リクエストのタイムアウト | 冪等な場合に限り、回数を制限してリトライ | 任意 | 未実行であることを確認してから1回リトライ |
409 |
競合または状態の不整合 | しない | しない | 業務処理の状態を確認し、同時書き込みを避ける |
422 |
パラメータの検証失敗 | しない | しない | パラメータを修正。構造化出力のschemaでよく発生 |
429 |
レート制限、同時実行数、またはクォータ | 待機時間を延ばしながらリトライ | リトライ失敗後に切り替え可 | まずエラーボディと Retry-After を確認 |
500 |
上流サービスの内部エラー | 回数を制限してリトライ | 連続して失敗する場合は切り替え | request idとエラーボディを記録 |
502 |
ゲートウェイエラー | 回数を制限してリトライ | 切り替え可 | ゲートウェイと上流のどちらの問題か切り分ける |
503 |
サービス利用不可 | 回数を制限してリトライ | 切り替え可 | Retry-After に従い、必要に応じて機能を縮退 |
504 |
ゲートウェイタイムアウト | 冪等な場合のみリトライ | 切り替え可 | まずタスクが実行済みか確認 |
529 |
上流サービスの過負荷 | 回数を制限してリトライ | 切り替え可 | 待機時間を延ばし、ジッターを加える。過負荷が続く場合は切り替え |
429は必ずしもレート制限とは限らない：エラーボディを読んで判断する
429 は特に誤判定しやすいエラーです。レート制限のほか、同時実行数の上限超過やモデルのクォータ枯渇を示すこともあり、まれに残高が関係する場合もあります。レート制限なら数秒待ってリトライすれば回復することが多いですが、クォータが尽きている場合は何度リトライしても効果がありません。すぐに最も高価なモデルへ切り替えても、コストが倍になるだけで問題は解決しません。
429 は次の手順で対処します。
- レスポンスヘッダーの
Retry-Afterを確認し、値があれば指定どおりに待機する。 - エラーボディのエラー種別フィールドを読み、rate limit、concurrency、quotaを区別する。
- レートや同時実行数の問題なら、待機時間を延ばしながら1〜2回リトライし、ローカルの同時実行数を減らす。
- クォータの問題なら、リトライを停止してアラートを出し、クォータのある経路に切り替える。
500 も考え方は同様です。必ずしもモデル自体の故障を意味するわけではなく、ゲートウェイや上流サービスに原因がある可能性もあります。まずrequest idとエラーボディの概要を記録しておきましょう。原因調査にも利用状況の照合にも役立ちます。
モデル API のエラー時のリトライ戦略：回数、バックオフ、Retry-After と冪等性
結論：リトライは一時的なエラーに限り、回数を 1～2 回に抑え、指数バックオフとランダムなジッターを必ず適用します。また、自動リトライは冪等なリクエストに対してのみ実行します。この4つの条件を満たさない場合は、自動リトライしないでください。
| パラメータ | 推奨値 | 説明 |
|---|---|---|
| リトライ可能なエラー | 429、500、502、503、504、529、ネットワークタイムアウト |
4xx のうち例外は 408、429 のみ |
| 最大リトライ回数 | 1～2 回 | 超過後は切り替えやアラートに移り、同じ場所でリトライを繰り返さない |
| バックオフ間隔 | 1s、2s、4s と指数的に増加 | 毎回ランダムなジッターを加え、複数のインスタンスが同時にリトライするのを防ぐ |
| Retry-After | 指定があれば優先して従う | ローカルのバックオフアルゴリズムより優先する |
| 冪等性の前提 | 必須 | 書き込み操作、ツール呼び出し、メッセージ送信、決済はデフォルトで自動リトライしない |
リトライ戦略の実装手順
- エラー分類関数を作る。ステータスコードとエラーボディを入力し、5つの分類のいずれかを出力します。他の処理はすべてこの分類結果に基づいて行い、ビジネスロジックのあちこちで数値を判定しないようにします。
- リクエストに冪等性のラベルを付ける。純粋なテキスト生成、要約、翻訳は通常、冪等とみなせます。リクエストがツールを起動したり、外部への書き込みを発生させたりする場合は、非冪等としてマークします。
- 非冪等なリクエストは先に状態を確認する。ツール呼び出しがタイムアウトしたら、まずタスクやデータベースの状態を確認し、実行されていないことを確かめてからリトライします。必要に応じて、ビジネス側の冪等キーを使って重複を防ぎます。
- 合計時間の上限を設定する。リクエストごとにリトライの合計所要時間に上限を設けます。そうしないと、ユーザー側のリクエストがすでにタイムアウトしているのに、バックグラウンドでリトライが続いてしまいます。
- 各試行を記録する。少なくとも request id、モデル ID、ステータスコード、エラー種別、レイテンシ、token 使用量、リトライ回数を記録します。
最後のステップは省略されがちですが、利用明細の照合にもトラブルシューティングにも欠かせません。APIYI の apiyi.com 経由で接続している場合は、コンソールで Key ごとの使用量と呼び出しログを確認できます。ローカルに記録した request id とプラットフォーム側のエラー情報を照合すれば、失敗がゲートウェイ、上流、あるいは自身のリクエストボディのどこで発生したのかを判断できます。
ストリームの中断は個別に処理する。ストリーミングリクエストが切断された場合は、まず受信済みの token 数と内容がすでに利用可能かを確認し、続きを生成するか、破棄するか、リクエストを再実行するかを判断します。長文出力のタスクを再実行する前に、前回の生成に対してすでに課金されている可能性があることも考慮してください。
🎯 トラブルシューティングのヒント：
500や529のように原因の所在を判断しにくいエラーが発生したら、まずエラーボディの原文と request id を保存し、APIYI の apiyi.com コンソールで同じ時間帯の使用量とログを確認しましょう。ステータスコードだけで結論を出さないことが大切です。
代替モデルへの切り替え戦略：能力の階層化、モデルマッピング、互換性の確認
結論：切り替えの前提は、代替モデルが同じタスクを処理できると事前に確認しておくことです。障害発生時に初めてフォールバック経路を使うと、そこで再び障害が発生する可能性が高くなります。
まず、モデルをフラッグシップ、汎用、軽量の3つに分類します。各タスクに主モデルと、同じ階層または隣接する階層の代替モデルを割り当てましょう。すべてのリクエストを最も高価なモデルにフォールバックさせるのは避けてください。上流サービスが一時的に不安定になっただけで請求額が膨らむおそれがありますし、単純なタスクの多くはフラッグシップモデルに切り替えてもメリットがありません。
| 能力項目 | 主モデル | 代替モデル | 互換性 | 切り替え前に行うこと |
|---|---|---|---|---|
| コンテキストウィンドウ | 実際の上限を記入 | 実際の上限を記入 | 要確認 | 実際に想定される最長の入力が収まるか確認し、収まらなければ切り詰める方針を決める |
| ツール呼び出し | ツールの schema、並列呼び出し | 同左 | 要確認 | 呼び出し ID の返却形式とパラメータ構造を検証する |
| 構造化出力 | JSON schema または厳密な JSON | 同左 | 要確認 | 同じ schema で成功率を検証し、422 を防ぐ |
| マルチモーダル入力 | 画像、音声、動画 | 同左 | 要確認 | 入力形式とサイズ制限を確認する |
| reasoning パラメータ | 推論レベルまたは思考に関するフィールド | 同左 | 要確認 | 非対応のパラメータは切り替え時に除去または変換する |
| 価格とレート制限 | コンソールを参照 | コンソールを参照 | 要確認 | 切り替え後のコストを試算し、利用上限が十分か確認する |
| 地域とコンプライアンス | 許容範囲 | 許容範囲 | 要確認 | 代替経路が事業上許容される地域とコンプライアンスの範囲内にあるか確認する |
この表はタスクの種類ごとに作成し、「互換性」欄には検証済みの結果だけを記入することをおすすめします。印象だけで記入するのは避けましょう。特に問題が起きやすいのは reasoning パラメータです。主モデルが対応する推論レベルのフィールドを代替モデルに送ると、400 や 422 が返されることがあります。切り替えロジックにはパラメータをそのまま転送するのではなく、適合させる処理を設けましょう。
モデルマッピング：モデル ID はコンソールを参照
切り替え時によくある単純なミスが、モデル ID を間違えて 404 が返されることです。「論理モデル名から実際のモデル ID へのマッピング表」を管理し、業務コードでは論理名だけを参照することをおすすめします。APIYI apiyi.com を通じて呼び出す場合、各モデルの正確な ID、利用可能な状態、価格はコンソールとドキュメントで確認してください。接続時の base_url は共通で https://api.apiyi.com/v1 を使用します。マッピング表を変更したら、リリース前にカナリアリクエストを一度実行しましょう。
予備モデルの検証とマルチモデルゲートウェイ：カナリアリクエスト、ログ、自動フォールバック
結論：予備モデルは本番投入前に実際のタスクで検証し、フォールバック後も出力を確認しましょう。ステータスコードが200かどうかを見るだけでは不十分です。マルチモデルゲートウェイは切り替えの手間を減らせますが、品質の確認は別途必要です。
予備モデルを検証する3つのステップ
- カナリアリクエスト。実際の業務タスクをいくつか選び、同じプロンプト、同じツール、同じ入力で、メインモデルと予備モデルそれぞれにリクエストを送ります。
- 同じタスクで比較。合格率、レイテンシ、最初のトークンが返されるまでの時間、トークンコスト、失敗率を比較します。ツール呼び出しを伴うタスクでは、呼び出しID、パラメータ構造、返却データの構造に互換性があるかも一つずつ確認します。
- フォールバック後の確認。実際に切り替えが発生したら、JSONをパースできるか、必須フィールドがそろっているか、ツールのパラメータが有効かなどを自動検証し、切り替えの理由と検証結果を記録します。
フォールバック経路は定期的にテストしましょう。例えば毎週、トラフィックの一部を意図的に予備モデルへ切り替え、経路が引き続き使えることを確認します。これにより、依存関係やパラメータ、モデルIDが知らないうちに使えなくなる事態を防げます。
ログには少なくとも次のフィールドを含めることをおすすめします。
- リクエストID、モデルID、エンドポイント、ステータスコード、エラー種別、エラー本文の要約
- レイテンシ、最初のトークンが返されるまでの時間、総所要時間、再試行回数、切り替え先
- 入力トークン数、出力トークン数、キャッシュヒット、推定費用
- ツール呼び出し名、呼び出しID、実行の成否
- 切り替え理由、切り替え後の検証結果
障害対策におけるマルチモデルゲートウェイの役割
障害対策のために複数のベンダーへ個別に接続する場合、少なくとも複数のキー、SDK、エラー形式を管理する必要があります。APIYI apiyi.com のような集約ゲートウェイを使えば、1つのキーでOpenAI、Claude、Gemini、DeepSeek、Qwenなどの主要モデルを呼び出せます。インターフェースはOpenAIの標準と互換性があり、ClaudeやGeminiのネイティブ形式にも対応しています。メインモデルと予備モデルを同じ接続コードで扱えるため、切り替え時に変更するのはモデルIDであり、連携経路全体ではありません。
プラットフォーム側には、マルチノードデプロイ、スマートルーティング、自動フォールバック、負荷分散も用意されており、接続先サービスの一時的な不安定さをある程度吸収できます。ただし、ゲートウェイ層の自動フォールバックは、業務ロジック側の判断に代わるものではありません。冪等性の確認、ツール呼び出しの重複排除、出力の検証は、引き続き自分のコードで行う必要があります。ゲートウェイが回線とノードの可用性を担い、アプリケーションがタスクの正確性を担う、という分担が堅実です。
💡 障害対策のヒント：メインモデルと予備モデルを設計する際は、まずAPIYI apiyi.comで同じキーを使い、両モデルに同じカナリアタスクを実行してみましょう。そのうえで、検証を通過した組み合わせをモデルのマッピングテーブルに登録します。新規ユーザーは、まず無料テスト枠を使って検証できます。
モデル API エラーに関するよくある質問 FAQ
結論：以下の5つの質問は、運用現場で特に判断に迷いやすいケースを取り上げています。回答に共通する原則は、「まず状況を判断し、それから対処する」ことです。
Q1：401 が返ったらリトライすべき？
いいえ。`401` は認証の失敗を意味します。リトライするとリクエストが増えるだけで、`429` を招く可能性もあります。APIキーが有効か、`Authorization` リクエストヘッダーの形式が正しいか、Base URL と APIキーが同じプラットフォームのものかを確認しましょう。APIYI apiyi.com を利用している場合は、コンソールで APIキーの状態を確認できます。
Q2：429 が返ったらすぐにモデルを切り替えるべき？
すぐに切り替えることはおすすめしません。まずエラーボディと `Retry-After` を確認しましょう。レート制限や同時実行数の制限であれば、待機時間を設けて1〜2回リトライすれば、通常は復旧します。利用枠を使い切った場合に、接続先を切り替えましょう。切り替え先には同じレベルの予備モデルを選び、一律に最も高価なモデルへ切り替えるのは避けます。
Q3：ストリーミング出力が中断したら、リクエストを再送すべき？
すぐに再送するのは避けましょう。ストリームの中断はリクエストの失敗を意味するとは限らず、すでにコンテンツが生成され、料金が発生している可能性があります。まず受信済みのトークン数と内容が使えるかを確認します。使える場合はそのまま残すか、続きを生成します。使えず、かつリクエストに冪等性がある場合は、1回再送します。実際の請求額はコンソールの利用状況で確認してください。
Q4：ツール呼び出しが重複して実行されたらどうする？
根本的な対策は、ツール層で冪等性を確保することです。業務側の冪等キーやタスク ID を使って重複を排除し、同じ ID では1回だけ実行します。ツール呼び出しがタイムアウトした場合は、まずタスクの状態を確認し、実行されていないことを確かめてからリトライしましょう。すでに重複が発生している場合は、呼び出し ID を使ってログを追跡し、余分な操作を補償または取り消します。
Q5：予備モデルへの切り替え後に 200 が返ったものの、結果が正しくない場合は？
200 はリクエストが成功したことを示すだけで、タスクの成功を保証するものではありません。JSON の構造や必須フィールド、ツールのパラメータの妥当性などを自動的に検証しましょう。検証に失敗した場合は失敗率に計上し、アラートの発報や人による確認につなげます。特定の予備モデルの組み合わせで受け入れ検証に頻繁に失敗する場合は、マッピング表から外し、カナリア検証をやり直しましょう。
本番公開前のチェックリストとまとめ：リトライ・切り替え・中止の判断
結論として、障害が起きてからその場で処理を追加するよりも、本番公開前に以下のチェックリストを一つずつ確認するほうが確実です。次の判断基準を覚えておきましょう。4xx はまず修正、5xx でリトライを検討、非べき等リクエストはいったん中止。
| 番号 | チェック項目 | 合格基準 |
|---|---|---|
| 1 | まずエラーの種類を判断 | すべてのステータスコードを5種類のいずれかに分類でき、未知のエラーは原則リトライしない |
| 2 | 4xx は自動リトライしない | 400、401、402、403、404、409、422 はすぐにアラートを出すか修正する |
| 3 | リトライか切り替えを決める | 一時的なエラーのみ、バックオフとジッターを伴って最大1〜2回リトライする |
| 4 | Retry-After を尊重 | レスポンスヘッダーに指定があれば、それに従って待機する |
| 5 | べき等性を確認 | ツール呼び出し、書き込み操作、メッセージ送信、決済は原則中止し、状態を確認してから判断する |
| 6 | ストリーム中断への対応 | まず受信済みのトークンと費用を確認し、むやみに再実行しない |
| 7 | 代替モデルの確認 | 能力チェック表をタスクの種類ごとに記入し、検証している |
| 8 | モデルのマッピング | 論理名からモデル ID へのマッピングがコンソールと一致している |
| 9 | 最後に出力を検証 | 切り替え後は 200 だけで判断せず、構造とフィールドを検証する |
| 10 | ログと訓練 | 重要なフィールドが揃っており、フォールバック経路を定期的に訓練している |
モデル API のエラー処理：重要なポイント
- リトライするタイミング：
429、500、502、503、529、およびべき等なリクエストのタイムアウト時。回数を制限し、バックオフを設けます。 - 切り替えるタイミング：リトライしても失敗する、上流サービスが継続的に利用できない、または利用枠が尽きた場合。ただし、代替モデルの検証が済んでいることが前提です。
- 中止するタイミング：
401などの 4xx 設定エラー、および状態が不明な非べき等リクエストの場合。 - 切り替えは成功とイコールではない：代替モデルが 200 を返した後も、出力を検証する必要があります。
- ゲートウェイとアプリケーションの役割分担：接続先の可用性はゲートウェイに任せ、タスクの正確性は業務コードで担保します。
エラー処理の良し悪しは、リトライをどれだけ積極的に行うかではなく、エラーが発生するたびに正しく判断できるかで決まります。まずはエラー分類、べき等性のタグ、ログフィールドを整え、その後に代替モデルを段階的に導入するのがおすすめです。代替接続先としては APIYI apiyi.com も選択肢の一つです。1つのキーで複数の主要モデルを利用でき、同じコードでメインと代替の検証・切り替えを行いやすくなります。価格と可用性はコンソールとドキュメントで確認してください。
📚 参考資料
- APIYI ドキュメントセンター：接続方法、モデル一覧、料金の説明
- リンク：
docs.apiyi.com -
補足：モデルID、価格、利用可否はドキュメントとコンソールをご確認ください
-
HTTPステータスコードの説明：
Retry-Afterなどの標準レスポンスヘッダーの意味 - リンク：
developer.mozilla.org/docs/Web/HTTP/Status - 補足：4xx、5xxの一般的な意味を理解するための資料です。具体的な内容は各モデルプラットフォームのエラーレスポンスをご確認ください
著者：APIYI 技術チーム
技術に関するお問い合わせ：APIYI公式サイト apiyi.com のホームページからお気軽にお問い合わせください。接続に関する資料は docs.apiyi.com のドキュメントセンターをご覧ください。
