DeepSeek APIのエラー対処法：原因の切り分けから代替モデルへの切り替えまで

DeepSeek APIのリクエストが失敗したら、最初にどの接続先が応答したのか、何が失敗したのか、処理はすでに完了している可能性があるかを確認します。認証、残高、リクエスト内容の問題は、再試行する前に修正してください。一時的なレート制限やサーバー障害には回数を制限した再試行を使い、それでも失敗する場合に限り、アクセス権、タスクとの適合性、データの取り扱いを確認済みの代替先へ切り替えます。

この記事は、アプリケーションやコーディング作業でDeepSeekを利用する開発者向けです。切り分け用リクエスト、エラー別の判断表、Ofoxのカタログに掲載された具体的な候補、ダウンロードできるPythonの切り替えサンプルを用意しました。サンプルが扱うのは、ストリーミングを使わない短いテキスト処理です。エージェントのセッションをそのまま移行したり、ツールを実行したりするものではありません。

2026年10月19日の確認範囲：公開ドキュメントとOfoxのカタログを確認し、ローカルで14件の合成テストに合格しました。有料のモデル推論や上流サービスの障害再現は行っていません。カタログに載っているだけでは、手元のアカウントで呼び出せること、出力が要件を満たすこと、次の障害時も利用できることは保証されません。この記事はOfoxが公開しており、本文ではゲートウェイの選択肢の一つとしてOfoxを取り上げています。

1. ローカル環境・アカウント・上流サービスのどこで失敗しているか確認する

まずDeepSeekのステータスページと、実際に利用しているゲートウェイの稼働情報を確認します。ステータスが正常でも、自分の経路が正常だと確定できるわけではありません。地域限定の障害、発生直後の問題、特定アカウントの不具合は反映されていない場合があります。

設定を変更する前に、次の情報を簡潔に記録してください。

例えば、同じプロンプトがアプリ内でだけ失敗し、最小構成のリクエストでは成功するなら、ペイロード、SDK、プロキシ、タイムアウト設定を調べます。あるモデルだけ失敗し、別のモデルは応答する場合も調査範囲を絞れます。ただし、モデルごとにアダプターや上流への経路が異なるため、ゲートウェイ全体が正常だとまでは判断できません。

調査中は、定期ジョブが処理を追加し続けないようにします。増え続けるキューと再試行によって、短い障害でも復旧が長引くことがあります。ジョブは元のIDとともに保持し、復旧時に全タスクの複製を作らないようにしてください。

2. エラーに応じて対処を選ぶ

2026年10月19日に取得した公式ドキュメントの英語画面です。参照ページのスクリーンショットであり、API呼び出しの失敗を撮影したものではありません。

以下の最初の7分類は、DeepSeekの公式エラーリファレンスに基づきます。ゲートウェイが独自のコードを追加したり、上流の応答を変換したりする場合があるため、HTTPステータスと、そのサービスが定義するエラー本文の両方を確認してください。

429は、待てば解決するとは限りません。クレジット枯渇や固定のクォータ上限にも使うプロバイダーがあります。サンプルは既知のクォータ関連コードで停止しますが、本番利用前に、利用先の公式エラースキーマに合わせて分類を拡張してください。同様に、タイムアウトはクライアントから見た現象であり、トークン消費がゼロだった証拠にはなりません。

DeepSeekはレート制限ガイドで、アカウント単位の同時実行数制限と、過負荷時のリクエストの挙動を説明しています。同じアカウントを共有する全ワーカーとAPIキーを横断して、実行中のリクエストを計測してください。一つのワーカーだけを遅くしても、アカウント全体では上限を超えたままになることがあります。

3. 小さな診断用リクエストを1回送る

DeepSeek直提供APIで現在ドキュメントに記載されているFlashのIDはdeepseek-flashです。ゲートウェイでも同じIDが使えるとは限りません。現在の対応関係は公式API概要で確認できます。初回の接続手順はDeepSeek API設定ガイドを参照してください。

トレースを無効にした信頼できるシェル、シークレット管理から設定済みの環境変数、空の作業ディレクトリを使います。次のリクエストは、診断用の合成フレーズだけを送ります。通常の推論料金が発生する可能性があります。過負荷のサービスに対して繰り返し実行しないでください。

umask 077
curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 45 \
  --dump-header response-headers.txt \
  --output response-body.json \
  --write-out 'HTTP %{http_code}; total %{time_total}s\n' \
  https://api.deepseek.com/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"model":"deepseek-flash","messages":[{"role":"user","content":"Reply with exactly: DIAGNOSTIC_OK"}],"stream":false,"max_tokens":128,"thinking":{"type":"disabled"}}'

接続5秒、全体45秒という上限は、この診断のために設定した値であり、DeepSeekのサービス保証ではありません。長い推論タスクには別の期限が必要な場合があります。--fail-with-bodyには対応したcurlが必要です。オプションを受け付けない場合はcurl --versionを確認してください。詳細なトレースを追加したり、本物のキーを入れたコマンドをサポート窓口に貼り付けたりしないでください。ローカルのプロセス情報から展開後の引数が見える場合もあるため、共有環境ではシークレット管理と連携したSDKを使います。

確認したい結果は、HTTP 200、DIAGNOSTIC_OKを含む空でない完全な回答、返された場合は使用量の記録です。choices[0].finish_reasonも調べます。長さ制限で終わった出力は、回答を完了した状態と同じ条件を満たしていません。失敗したら機密情報を除いたエラー詳細を残してください。上の2ファイルは次回実行で上書きされる可能性があるため、試行を比較する場合は別々のディレクトリを使います。

成功したら、実際のリクエストに必要な機能を一つずつ戻します。長い会話履歴、推論、構造化出力、ツール、最後にストリーミングを追加すると、どの変更から失敗するかを特定しやすくなります。接続確認だけのために、本番の会話を新しいプロバイダーへ送らないでください。

4. どの種類の代替先が必要か判断する

「フォールバック」と呼ばれる切り替えには、次の3種類があります。

同じプロバイダーの同じアカウントに属する2本のAPIキーは、クォータを共有している可能性があります。異なるモデル名が同じデプロイ先を指したり、別のゲートウェイが同じ上流を呼び出したりする場合もあります。推論を提供するプロバイダーが公開されていれば記録し、経路が不明なら確認してください。URLが違うだけでは、障害からの独立性を検証したことにはなりません。

単純な要約や情報抽出なら、別途検証したテキストモデルを縮退運転に使える場合があります。コード変更なら、結果に対してプロジェクトのテストを実行します。画像理解なら、実際の画像入力経路を確認します。ツールを使うエージェントでは、システム指示、完了済みツールの結果、保留中の操作状態を保持してください。プロバイダー固有の推論ブロックを、確認せず別のプロトコルへコピーしないことも必要です。

プライバシーや契約上の条件によって代替先へデータを送れない場合は、タスクをキューに保持するか、一時的に利用できないことを明確に返します。可用性を理由に、承認済みのデータ取り扱い範囲を越えてはいけません。

5. 正確なモデルIDでOfoxの代替経路を準備する

10月19日にOfoxの公開モデルカタログから取得した候補は次のとおりです。これはカタログの確認であり、推論の成功確認でも、特定モデルの優位性を推奨するものでもありません。

カタログでは、これらのモデルにOpenAI Chat Completionsが掲載されています。一方、2つのDeepSeekモデルでは、組み込みのweb_searchとweb_fetchが個別にfalseと記載されています。DeepSeek直提供APIのSearch/Fetch機能や課金ルールが、OfoxのモデルIDでもそのまま適用されるとは考えないでください。この記事の切り替えで使うのは、テキストのChat Completionsだけです。プロバイダー固有の検索機能は使いません。

準備の手順は次のとおりです。

1. 現在のカタログ項目、対応プロトコル、アカウントに適用される料金を確認します。この記事ではOfoxの価格を提示せず、無料利用も約束していません。
2. 要件に合う場合はOfoxアカウントを作成し、API Keysでキーを作成します。認証ドキュメントに従ってください。OfoxのキーとDeepSeek直提供APIのキーは別のアカウントに属します。
3. OpenAI互換の接続には、SDKのベースURLとしてhttps://api.ofox.ai/v1を指定します。HTTPで直接呼ぶ場合は/chat/completionsを1回だけ追加します。/v1/v1の重複や、この経路へのAnthropicメッセージ形式の送信を避けてください。
4. 候補のモデルIDを正確にコピーし、機密情報を含まない診断タスクを送ります。返された本文、使用量、リクエスト記録を確認してください。入金が必要な場合は、アカウントの条件を確認したうえで別途行います。
5. 以下の代表タスクと費用の確認を通過してから、本番の切り替え先に追加します。

主経路と代替経路の両方でOfoxを使うなら、Ofoxのゲートウェイは共通の依存先として残ります。ゲートウェイ自体の障害にも備える必要があるなら、その外部の経路を承認してください。これらの候補について、運用上の独立性や稼働率保証を確認したわけではありません。

6. 回数を制限した再試行と切り替えをローカルでテストする

Pythonサンプルとテストをダウンロードできます。パッケージにはfailover.py、test_failover.py、READMEが含まれます。新しいディレクトリに展開してから、次を実行してください。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -m unittest -v

10月19日の実行では、注入した応答と合成の認証情報を使う14個のテストメソッドが合格しました。これらのテストはネットワーク呼び出しを行いません。主経路の成功、503からの回復、2回失敗後の代替経路、再試行しないHTTPエラー、クォータとレート制限の429の区別、試行回数の消尽、処理状況が不明な通信失敗、明示的な再送許可、TLS失敗、不正な成功応答、秒数と日付のRetry-After処理を確認しています。

制御ロジックは、最大で主経路2回、代替経路1回の試行を許可します。再試行や経路変更の前にRetry-Afterに従います。指定された待ち時間がサンプルの30秒の待機予算を超える場合は停止し、呼び出し元でタスクをキューに戻せるようにします。利用できるヘッダーがなければ、上限付きでランダムな待ち時間を入れます。意図しない接続先変更を避けるため、リダイレクトは無効です。各経路には、それぞれ専用のキーとモデルを設定します。

実際にリクエストを送る場合は、承認済みのシークレット管理を通じて次の環境変数を設定します。

DEEPSEEK_API_KEY = your direct DeepSeek key
BACKUP_BASE_URL  = https://api.ofox.ai/v1
BACKUP_MODEL     = deepseek/deepseek-v4.1-flash-1017
BACKUP_API_KEY   = your Ofox key
BACKUP_DISABLE_THINKING = 1

DEEPSEEK_API_KEYはDeepSeek直提供APIのキー、BACKUP_API_KEYはOfoxのキーです。このDeepSeekの代替先では、短い診断応答のためにBACKUP_DISABLE_THINKING=1を指定して推論を明示的に無効にします。別系統のモデルを選ぶ場合は、このフラグを削除し、そのモデルの公式設定と十分な出力予算を使ってください。DeepSeek専用のパラメーターを自動で転送しないようにします。このパラメーター設定も、実際の経路で確認する必要があります。

続いてpython failover.pyを実行します。固定のテキストプロンプトを送信するため、料金が発生する可能性があります。選択した経路、指定・返却されたモデル、テキスト、使用量、取得できた場合はリクエストIDを出力します。期待する回答はFALLBACK_TEST_OKです。このマーカーが正確に含まれるか自分で確認してください。主経路が通常どおり成功しても、実際の代替経路を検証したことにはなりません。代替先だけを確認するには、そのドキュメントに記載された経路へ診断リクエストを直接送ります。主サービスを意図的に過負荷にしたり、壊したりしないでください。

通信失敗時は、サーバーがすでにリクエストを受理している可能性があるため、既定では停止します。python failover.py --allow-ambiguous-replayを指定すると、この固定された副作用のないテキストタスクについて、再試行を明示的に許可します。これはツール操作、支払い、メール送信、ファイル変更を再実行する許可ではありません。純粋な文章生成でも二重に課金される可能性があります。

サンプルはRequestsを直接使い、SDKによる暗黙のステータス再試行を挟みません。この方針をSDKに組み込む場合は、SDKの再試行を無効にするか、同じ試行回数の予算に含めてください。接続5秒と、読み取りの無通信状態30秒というタイムアウトは、処理全体の経過時間の上限ではありません。本番コードには、全体の期限、共有の同時実行数制御、永続化したサーキット状態、タスク別の出力検証も必要です。

7. ストリーミングとツール実行は分けて復旧する

出力がすでにユーザーへ届いた場合、その末尾に別モデルの回答の冒頭をつなげてはいけません。最初の応答は中断として扱います。ユーザーやアプリが生成をやり直す場合は、新しい回答を分離し、両方の試行を記録してください。接続上で届くハートビートや空白は、有用な出力とは限りません。接続の通信状況とともに、意味のある内容が届くまでの時間も追跡します。

ツールでは、生成と実行は別の段階です。モデルがツール呼び出しを返しても、操作が実行されたとは限りません。逆に、実行側が操作を終えた後に通信が切れても、操作が失敗したとは限りません。タスクID、操作の引数または安全な参照、実行状況、結果を記録する永続的な操作台帳を持たせてください。再開前に、結果が不明な操作の状態を照合します。下流サービスが冪等性に対応していれば利用しますが、独自の冪等性ヘッダーを付けるだけで相手が対応すると考えてはいけません。

実用的な復旧順序は、新しい操作の送出を止め、完了済みの操作を特定し、保存した結果を復元し、保留中の操作を検証してから、承認済みモデルで再開することです。安全に状態を照合できなければ、確認のために停止します。ダウンロード用サンプルには、意図的にツール実行器やストリーミング解析処理を含めていません。

8. 代替先を受け入れる条件、費用、主経路へ戻す手順を決める

障害の前に、代表的なケースを準備してください。通常のタスク、対応範囲内の長い入力、必要なら構造化出力、必須のツール操作や画像処理を含めます。ケースごとに正しさの基準を決めます。形式上は正しいJSONでも値が誤っていることがあり、コンパイルが通るコードでも必要な動作を満たすとは限りません。

経路、指定した正確なモデル、返されたモデル名があればその値、入力サイズ、パラメーター、遅延、終了理由、使用量、課金記録、合否を記録します。使用量がない場合は不明であって、料金ゼロではありません。主経路でプロンプトがキャッシュされても、代替経路でキャッシュにヒットするとは限りません。請求額を照合する際は、失敗と再試行の分も含めてください。

縮退運転の方針として、どのタスクに代替先を使えるか、許容費用、最大試行回数、失敗後の対応を決めます。簡単な社内向け要約なら文体の違いを許容できても、財務情報の抽出や破壊的なコード操作には確認が必要な場合があります。別モデルが速く応答するというだけで、黙って切り替えないでください。

失敗が続く場合は、その経路のサーキットを開いて通常トラフィックの送信を止めます。一定の待機時間の後に小さな確認リクエストを許可し、代表的な確認が連続して成功してから、徐々にトラフィックを戻します。しきい値は、ブログの一律の数字ではなく、アプリの期限とリスクに合わせて決めてください。失敗が1回発生するたびに経路を往復しないようにします。復旧後も代替先の設定を保持し、障害の経緯を時系列で記録します。

それでもサポートが必要なら、時刻、機密情報を除いたステータスとコード、指定モデル、クライアントのバージョン、リクエストID、合成データだけを使う最小の再現手順を送ります。キー、非公開のプロンプト、顧客ファイルは除いてください。クライアントごとの詳しい問題にはDeepSeekのクライアント間の違いを調べるガイド、一般的なステータスの意味にはAPIエラーリファレンスが役立ちます。

受け入れ条件は具体的です。失敗の原因を正しく切り分け、再試行の上限をテストし、承認済みの代替先が実際のタスクを完了でき、操作を重複実行せずに復旧できること。カタログへの掲載とHTTPの成功応答は、その確認過程の一部です。