guide

OpenRouter 429「Provider Returned Error」の解決方法：レート制限、上流プロバイダー、フォールバック戦略

EvoLink Team

Product Team

2026年5月13日

15 分

OpenRouter へのリクエストが 429 または 「provider returned error」 で失敗している場合、修正方法はエラーの発生元によって異なります。

これら2つのエラーはログ上では似て見えますが、根本原因が異なります：

429 Too Many Requests：レート制限に達したためリクエストが拒否された
Provider returned error：OpenRouter はリクエストを受け付けたが、上流のモデルプロバイダー（OpenAI、Anthropic、Google など）がエラーを返した

これらを混同すると、誤った対処をしてしまいます。このガイドでは原因の切り分け方と適切な対応方法を解説します。

まとめ

OpenRouter 自体からの 429 は、OpenRouter のレート制限またはクォータに達したことを意味します。
「provider returned error」は、上流プロバイダーがリクエストを拒否したことを意味します（OpenRouter ではありません）。
レスポンスヘッダーとエラー本文を確認して、2つを区別してください。
対処法は異なります：OpenRouter の 429 にはキーやティアの変更が必要で、プロバイダーエラーには上流の診断やルート変更が必要です。
本番ワークロードでは、エラーが発生する前にフォールバックを設計しておきましょう。

ステップ 1：エラーレスポンスを注意深く読む

エラーを受け取ったら、以下の3つを確認してください：

シグナル	確認場所	何がわかるか
HTTP ステータスコード	レスポンスステータス	429 = レート制限、502/503 = 上流障害
エラーメッセージ本文	JSON レスポンスの `error.message`	「provider returned error」や特定のレート制限メッセージが表示されることが多い
レスポンスヘッダー	`x-ratelimit-remaining`、`retry-after`	OpenRouter 自体がスロットリングしているかどうか

典型的な OpenRouter 429 は以下のようになります：

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Please slow down."
  }
}

典型的なプロバイダーエラーは以下のように異なります：

{
  "error": {
    "code": 502,
    "message": "Provider returned error: [upstream error details]"
  }
}

対処法が異なるため、この区別は重要です。

ステップ 2：エラーの発生元を特定する

以下の判定ツリーを使ってください：

リクエスト失敗
├── HTTP 429 + OpenRouter レート制限メッセージ
│   → 原因：OpenRouter レベルのレート制限
│   → 対処：リクエスト頻度を下げる、ティアをアップグレード、またはディレイを追加
│
├── HTTP 429 + メッセージに「provider returned error」
│   → 原因：上流プロバイダーのレート制限がパススルー
│   → 対処：プロバイダーのクォータを確認、モデル変更、またはフォールバックルートを追加
│
├── HTTP 502/503 + 「provider returned error」
│   → 原因：上流プロバイダーの障害または一時的なエラー
│   → 対処：バックオフ付きリトライ、プロバイダー変更、またはフォールバック使用
│
└── HTTP 400/401 + エラーメッセージ
    → 原因：不正なリクエスト、無効なキー、またはモデルが見つからない
    → 対処：API キー、モデル ID、リクエストフォーマットを確認

ステップ 3：OpenRouter レベルの 429 を修正する

429 が OpenRouter 自体から発生している場合（プロバイダーからのパススルーではない場合）、以下を順に確認してください：

3.1 現在のレート制限ティアを確認する

OpenRouter はアカウントティアに基づいてレート制限を適用します。無料ティアのユーザーは、有料ユーザーに比べて制限が大幅に低くなっています。

対応：OpenRouter ダッシュボードで現在の制限と使用状況を確認してください。

3.2 リクエスト頻度を下げる

ティアの許容量を超えてリクエストを送信している場合：

import asyncio
import random

async def call_with_backoff(make_request, max_retries=5):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                # Respect retry-after if present, otherwise use jittered backoff
                delay = min(30, (2 ** attempt) + random.random())
                await asyncio.sleep(delay)
            else:
                raise

3.3 トラフィックを時間的に分散させる

エージェントワークロードはバースト的なパターンを生みがちです。50リクエストを同時に送信するのではなく：

セマフォで並行数を制限する
バッチ間に小さなディレイを入れる
フォアグラウンドとバックグラウンドのキューを分離する

ステップ 4：上流プロバイダーのエラーを修正する

エラーメッセージに「provider returned error」が含まれている場合、問題は上流にあります。OpenRouter はリクエストを転送しましたが、モデルプロバイダーがそれを拒否しました。

4.1 上流の一般的な原因

上流の原因	表示される内容	確認方法
プロバイダーのレート制限	パススルーされた 429	同じモデルがより低いリクエスト頻度で動作するか確認
プロバイダーの障害	パススルーされた 502/503	プロバイダーのステータスページを確認（例：status.openai.com）
モデルの廃止または利用不可	404 またはモデルが見つからない	OpenRouter のモデルリストでモデル ID がまだ有効か確認
地域制限	403 またはアクセス拒否	一部のプロバイダーは地理的にアクセスを制限している
入力が大きすぎる	400（コンテキスト/トークンに関するメッセージ付き）	入力がモデルのコンテキストウィンドウを超えていないか確認

4.2 別のプロバイダールートに切り替える

OpenRouter はリクエストを上流プロバイダーにルーティングします。あるプロバイダーがレート制限をかけている場合、同じモデルが別のプロバイダーパス経由で利用できる可能性があります。

以下を確認してください：

そのモデルが OpenRouter 上で複数のプロバイダーオプションを持っているか
リクエストでプロバイダーの優先順位を設定できるか
同等の能力を持つフォールバックモデルが利用可能か

4.3 エラータイプを区別するリトライロジックを追加する

すべてのエラーを同じ方法でリトライしないでください：

async def smart_retry(make_request, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await make_request()
        except Exception as e:
            error_msg = str(e)

            # Do NOT retry: bad request, auth error, model not found
            if any(code in error_msg for code in ["400", "401", "404"]):
                raise

            # Retry with backoff: rate limit or provider error
            if any(code in error_msg for code in ["429", "502", "503"]):
                delay = min(30, (2 ** attempt) + random.uniform(0, 1))
                await asyncio.sleep(delay)
            else:
                raise

ステップ 5：事前にフォールバックを設計する

本番環境では、上流エラーが発生するかどうかではなく、発生したときにシステムが適切にデグレードするか、それともクラッシュするかが問題です。

フォールバックチェックリスト

フォールバック層	実装すべきこと	理由
バックオフ付きリトライ	`retry-after` を尊重したジッター付き指数バックオフ	負荷を増幅させずに一時的な障害に対処する
モデルフォールバック	プライマリモデルが失敗した場合、代替モデルにルーティング	1つのモデルパスがダウンしてもワークフローを維持する
プロバイダーフォールバック	1つのプロバイダーがエラーを返す場合、別のルートを試す	単一プロバイダーへの依存を軽減する
キュー + サーキットブレーカー	N回連続で失敗した経路への送信を停止	リトライの嵐が問題を悪化させるのを防ぐ
グレースフルデグレード	小さいコンテキスト、安価なモデル、またはキャッシュされたレスポンス	エンドユーザーにとって完全な障害よりも良い

統合 API ゲートウェイを検討すべきタイミング

上流の障害に対処するために OpenRouter 上にフォールバックロジックを構築している場合、実質的にルーティング層の上にルーティング層を構築していることになります。

そうなった場合、プロバイダールーティング、フォールバック、モデル選択をビルトイン機能として備えたゲートウェイを使う方が、アプリケーションレベルのコードで実装するよりもシンプルかもしれません。

EvoLink の Smart Router はゲートウェイレベルでこれを処理します：

プロバイダー間で自動的にルーティング
レスポンスに実際に使用されたモデルを返す
OpenAI 互換のリクエスト形式 -- コードの書き換え不要
ルーティング手数料なし

curl https://api.evolink.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "evolink/auto",
    "messages": [
      {"role": "user", "content": "Your prompt here"}
    ]
  }'

これによりクライアントサイドのリトライロジックが不要になるわけではありませんが、プロバイダー選択とフォールバックをアプリケーションコードの外に移すことができます。

エラー原因ツリー（参考）

OpenRouter リクエスト失敗
│
├── OpenRouter からの 429
│   ├── 無料ティアの制限 → アカウントをアップグレード
│   ├── バーストトラフィック → 並行制御を追加
│   └── 持続的な高トラフィック → ティア制限を確認
│
├── 「Provider returned error」
│   ├── Upstream 429
│   │   ├── プロバイダーのレート制限 → 頻度を下げるかプロバイダーを変更
│   │   └── 共有クォータの枯渇 → 組織レベルの制限を確認
│   ├── Upstream 502/503
│   │   ├── プロバイダーの障害 → ステータスページを確認、待機または変更
│   │   └── 一時的な障害 → バックオフ付きリトライ
│   └── Upstream 400
│       ├── コンテキストが長すぎる → 切り詰めるかモデルを変更
│       ├── 無効なパラメータ → API ドキュメントを確認
│       └── モデルの廃止 → モデル ID を確認
│
└── その他のエラー
    ├── 401 → 無効な API キー
    ├── 404 → モデルが見つからない
    └── ネットワークエラー → 接続を確認

次のステップ

現在のエラーを確認する：ステップ 2 を使って、OpenRouter の 429 なのかプロバイダーエラーなのかを特定してください。
的確な修正を適用する：レート制限の修正をプロバイダーエラーに適用したり、その逆をしたりしないでください。
構造化されたリトライロジックを追加する：リトライ可能なエラーとリトライ不可能なエラーをコード内で区別してください。
必要になる前にフォールバックを設計する：本番システムは単一の上流パスに依存すべきではありません。

How to Reduce 429 Errors in Agent Workloads -- エージェント固有のバーストトラフィックに対するより深いパターン
Best OpenRouter Alternatives in 2026 -- OpenRouter の制限が繰り返し問題になる場合のルーティングオプション比較
Best AI API Platform for Production Reliability -- 信頼性の高い本番 API プラットフォームを選ぶためのフレームワーク

Explore EvoLink Smart Router

FAQ

OpenRouter の「provider returned error」とは何ですか？

OpenRouter がリクエストを受け取り、上流のモデルプロバイダーに転送したが、プロバイダーがエラーを返したことを意味します。エラーは OpenRouter 自体からではなく、OpenAI、Anthropic、Google など、そのモデルを提供しているプロバイダーからのものです。

OpenRouter の 429 と上流プロバイダーの 429 は同じですか？

いいえ。OpenRouter レベルの 429 は、OpenRouter 自体のレート制限に達したことを意味します。「provider returned error」としてパススルーされたプロバイダーレベルの 429 は、上流プロバイダーがリクエストを拒否したことを意味します。対処法は異なります。

「provider returned error」でリトライすべきですか？

エラーの種類によります。上流が 502/503（一時的な障害）を返した場合、バックオフ付きリトライは合理的です。400（不正なリクエスト）や 404（モデルが見つからない）を返した場合、リトライしても解決しません。リクエスト自体を修正してください。

問題が API キー、クォータ、プロバイダーのいずれにあるかをどう判断しますか？

以下の順序で確認してください：（1）API キーは有効ですか？簡単なテストリクエストを試してみてください。（2）OpenRouter ダッシュボードでクォータとレート制限の使用状況を確認してください。（3）キーとクォータに問題がなければ、エラーは上流プロバイダーからのものと考えられます。エラーメッセージの詳細を確認してください。

統合 API ゲートウェイでプロバイダーエラーを完全になくすことはできますか？

上流プロバイダーの障害を防ぐことができるゲートウェイはありません。ただし、ルーティングとフォールバックが組み込まれたゲートウェイは、あるパスが障害を起こしたときに自動的に代替プロバイダーやモデルに切り替え、アプリケーションへの影響を軽減できます。

OpenRouter から別のルーティングソリューションに切り替えるべきタイミングは？

以下の場合に検討してください：（1）プロバイダーエラーが本番環境で繰り返し発生する問題になっている、（2）OpenRouter が提供しないフォールバックロジックが必要、（3）ワークロードが複数のモダリティ（テキスト＋画像＋動画）にまたがっている、（4）ルーティングの判断をアプリケーションコードではなくゲートウェイレベルで管理したい。

すべての記事

#openrouter 429 #provider returned error #rate limit #トラブルシューティング #AI API エラー