> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rockapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 本番向け API 連携：タイムアウト・再試行・冪等性の確認

> API 連携で確認すべきタイムアウト、再試行予算、冪等性、レート制限、ストリーミング、段階的な本番導入を解説します。

テストリクエストの成功で確認できるのは接続性です。本番では、上流の遅延、レスポンスの消失、上限超過、重複送信にも対処する必要があります。失敗した呼び出しや繰り返した操作は費用を増やし、ユーザーに結果を分かりにくくするため、トラフィックを増やす前に動作を決めます。

## 一件のリクエストと適用条件を確認する

サービスごとにベース URL、エンドポイント、認証、必須フィールド、レスポンス形式、課金単位を確認します。マーケットプレイスの API が、AI ゲートウェイと同じ接続先や形式を使うとは限りません。契約と検証の流れは [OpenAPI の購読とオンラインテスト](https://docs.rockapi.ai/ja/blog/buyers/how-to-subscribe-and-test-openapi.md) を参照してください。

認証情報はサーバー側のシークレット管理基盤や環境設定に保存し、開発用と本番用を分けます。ログでは認証ヘッダーをマスクしてください。機密情報を取り除いた成功リクエストと、アプリが依存するレスポンス項目を連携の基準として残します。

## 期限と再試行予算を決める

接続、レスポンス読み取り、操作全体の期限を設定します。ストリーミングには無通信時のタイムアウトも必要です。測定結果とユーザーの許容待ち時間に基づいて選びます。短い操作なら接続 5 秒、全体 30 秒、再試行は最大 2 回から試験を始める例が考えられます。これは例示設定であり、Rock API の既定値ではありません。

| 状況 | アプリケーションの対応 |
| - | - |
| `400` または検証エラー | 入力を直し、同じ内容を再送しない。 |
| `401` または `403` | 認証情報、権限、契約を確認し、自動再試行を止める。 |
| `429` | レート制限とクォータ切れを区別し、同時実行数を下げてレスポンスを確認する。 |
| 一時的な `5xx` や通信障害 | 繰り返しが安全で残り時間がある場合だけ再試行する。 |

ランダムな揺らぎを加えた指数バックオフを使い、サービスが `Retry-After` を返す場合は従います。総試行回数と経過時間に上限を設けてください。SDK、プロキシ、ワーカーの設定を合わせて確認し、多段の再試行で呼び出し数が増幅しないようにします。

## 結果不明の操作を扱う

タイムアウトは、サーバーが処理を拒否した証拠ではありません。POST の再送で別のリソース、生成結果、課金が発生する可能性があります。冪等性キーは、エンドポイントの対応範囲と保持期間が文書化されている場合だけ利用します。任意のヘッダーを追加しても保証にはなりません。

対応がなければローカルの操作 ID を保持し、文書化された状態確認 API や利用記録で照合してから重要な処理を再送します。ストリーミングでは分割データ、切断、キャンセル、終了マーカーを検証してください。途中まで受け取った生成処理をやり直すと、内容が変わり追加消費も生じ得ます。

## 上限をテストして段階的に導入する

容量に上限のあるキューと、サービス単位の同時実行制限を使います。リクエスト頻度と、トークン、文字数、日次・月次枠を分けて扱います。残り枠と残高を監視し、すべての `429` をプラン変更で解決しようとしないでください。

安全な環境で無効な認証、不正入力、枠の消費、遅い応答、ストリーム中断、重複送信を検証します。小規模に公開し、切り戻し条件を定めます。ID、状態、時間、再試行数、確定した使用量を記録し、私的な入力内容は残しません。費用と P95 レイテンシが受け入れ基準を満たしてから拡大します。

> [card] [AI API の安全性とプライバシーを確認する](https://docs.rockapi.ai/ja/blog/buyers/ai-api-security-privacy.md)
>
> 本番利用前にデータ経路、保存条件、認証情報、インシデント対応を評価します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.