レート制限と使用量
リクエストがプランに対してどのようにカウントされるか、429レスポンスの内容、そして1回のリクエストのサイズ制限について説明します。
将来対応予定です。 レート制限、使用量の上限、そして 402、403、429 の各レスポンスは API 契約の一部ですが、まだ適用されていません。このページでは、あらかじめ対応したクライアントを構築できるように、それらの挙動を説明します。適用されていないため、これらについての具体的な数値のしきい値はここには記載していません。リクエストサイズの制限は例外で、現在すでに適用されており、その上限は以下に記載しています。
PDF Blocks は、負荷がかかった状況でも適切に振る舞い、使用量を常に確認できるように設計されています。このページでは、使用量がどのように計測されるか、レート制限がどのように現れるか、そしてリクエストのサイズをどう決めればよいかを説明します。
使用量の計測方法
使用量はプランごとに計測され、ダッシュボードで確認できます。処理したドキュメント数とリクエスト数のどちらについても、プランに対してどれだけ消費したかを示す正式な情報源はダッシュボードです。消費状況を確認し、プランの上限にどれだけ近づいているかを把握するために、ダッシュボードをチェックしてください。
API はステートレスであるため、各リクエストは個別に計測されます。まとめて精算するセッションやバッチはありません。分割のような複数ドキュメントを扱うアクションであっても、カウントはリクエスト1回分です。
レート制限と429レスポンス
レート制限が適用されると、プランの上限を超えたリクエストには 429 Too Many Requests と problem+json 形式のレスポンスボディが返されます。429 は一時的なものです。ペースを落とせば、同じリクエストは成功します。
初日からこれに対応できるクライアントを構築しましょう。
- 指数バックオフを使う。
429を受け取ったら、すぐにタイトなループで再試行するのではなく、再試行前に待機し、429が続くたびに待機時間を増やしてください（たとえば倍にします）。 Retry-Afterに従う。 レスポンスにRetry-Afterヘッダーが含まれている場合は、独自の待機時間を使うのではなく、少なくともその時間だけ待ってから再試行してください。- ジッターを加える。 並列に動くワーカーが足並みをそろえて再試行しないよう、バックオフの時間をわずかにランダム化してください。
- 再試行回数の上限を設ける。 永遠に再試行するのではなく、妥当な回数を試したら諦めて、失敗を呼び出し元に伝えてください。
同じバックオフ戦略は、まれに発生する 5xx サーバーエラーにも当てはまります。
リクエストサイズの制限
各プランには、入力ドキュメント1件あたりのサイズ上限があります。Free プランは5MB、それ以外のすべてのプランは10MBです（料金を参照）。この上限を超える本文を持つリクエストは、処理されることなく 413 Payload Too Large として拒否され、problem+json 形式のレスポンスボディが返されます。429 と異なり、413 は再試行しても成功しません。より小さいファイルを送るか、頻繁により大きいサイズが必要な場合はアカウントの上限引き上げをご相談ください。
請求に関するレスポンス
アカウントに関連する、個々のリクエストとは別の予約済みコードがさらに2つあります。
402 Payment Required：プランの請求またはクォータに関する状態を示します。ダッシュボードから解消してください。403 Forbidden：キーは有効ですが、要求されたリソースを使用する権限がありません。
どちらも、レスポンスの完全な形式とあわせてエラーカタログに記載されています。