# レート制限

> 公開 API のレート制限の値と、429 を受け取ったときのハンドリングについて

サービスを安定して提供するため、API にはレート制限が設定されています。制限を超えたリクエストは `429 Too Many Requests` でエラーとなります。

## 制限値

| 対象                     | 上限                                            |
|--------------------------| ----------------------------------------------- |
| 送信元 IP アドレスあたり | 1 分間に 120 リクエスト（平均 2 リクエスト/秒） |
| バースト                 | 1 秒間に 5 リクエストまで                       |

- 上限は送信元 IP アドレス単位で計測されます。同じ IP アドレスから複数のクライアント（`client_id`）やアクセストークンで呼び出す場合は合算して数えます。
- PDF のアップロード（S3 への直接アップロード）はこの制限に含まれません。
- システムの安定性を確保するため、上記に達していなくても一時的に `429` を返すことがあります。
- 制限値は利用状況に応じて見直すことがあります。緩和する場合は予告なく行い、厳しくする場合は事前にご案内します。上限の引き上げが必要な場合はサポートデスク（[de-api@yubin.app](mailto:de-api@yubin.app)）までご相談ください。

## 429 レスポンス

レート制限による `429` はリクエストが API に届く前に返るため、ボディは [認証エラー](/guides/authentication/#認証エラー)と同じく problem+json ではありません。HTML など固定でない形式になるため、エラー判定は必ずステータスコードで行ってください。

## 実装のガイドライン

- `429` は再試行してください。`Retry-After` ヘッダが付いている場合はその秒数待ってから、付いていない場合は指数バックオフ（1 秒 → 2 秒 → 4 秒 … 最大 30 秒程度）で再試行します。`429` を受け取った直後に間隔を空けずに再送すると、制限が解除されるまでの時間が延びます。
- アクセストークンは使い回してください。トークンは `expires_in` の期限まで有効です。リクエストのたびにトークンエンドポイントを呼ばないでください。トークンエンドポイントへの過度な呼び出しも制限されることがあります。
- 大量の依頼は平準化してください。一括送信は並列数を 2〜4 程度に抑え、キューで順次送ります。1 通の発送には作成・確定で最低 2 リクエスト必要なので、毎分 120 リクエストは 1 時間あたりおよそ 3,000 通に相当します。