API制限

API リクエストにはリクエストレート制限と、リソース制限の2種類の制限があります。加盟店と開発者は、API の呼び出しを最適化するためにこれらの制限を理解する必要があります。

また、このレート制限とは別に、同一のカード、同一のリカーリングトークン、同一金額で30秒以内に課金処理すると重複エラー（エラーコード：311）になる仕様がございますのでご注意ください。

レート制限

UnivaPay API はアクセスする先のリソースとパスに応じてレート制限を設定しています。最初に、加盟店は、バーストレートと呼ばれる、一度に送信できるリクエスト数の 残高 を受け取ります。これを使い果たすと、バーストレートが完全に回復するまで、残高は一定のレートで補充されます。レート制限を超えたリクエストはToo Many Requests エラーとなります。レート制限値と残りの実行可能なリクエスト回数はAPIレスポンスヘッダで取得できます。以下はAPIから返却されるヘッダの例です:

X-Remaining-Requests-Exact: 9
X-Remaining-Requests-Route: 29
X-Requests-Per-Minute-Exact: 120
X-Requests-Per-Minute-Route: 1200

例

100 リクエストの バーストレート 、かつ毎分 1,200 リクエストのレートに設定されたAPIにリクエストを送信する場合を考えます。

この場合、加盟店は 100 リクエストを一度に送信することができますが、これはバーストレートを使い果たします。そこからは、APIは加盟店の残高を 1 ミリ秒毎に 0.02 リクエスト（1,200 リクエスト毎分 ÷ 60,000 ミリセカンド)のペースで回復します。つまり、加盟店は次のリクエストを送信する為には少なくとも 50 ミリ秒待機する必要があります。

代わりに 5 秒間待機した場合、100 リクエストを一度に送信することができます。5秒以上待機した場合でも、加盟店が一度に送信できるリクエスト数の最大は 100 のままとなります。

レート制限の種類

レート制限には課金レート制限と標準レート制限があります。 課金レート制限が適用されるAPIは、標準レート制限の適用は受けません。また、逆も同様となります。

以下で詳しく説明します。

課金レート制限

この制限は下記のAPIに対して適用されます:

  • POST /tokens
  • POST /charges
  • POST /subscriptions

この制限は以下のように設定されています:

  • レート制限: 3,000 リクエスト毎分
  • バーストレート: 100 リクエスト

また、APIのレスポンスには以下のヘッダが含まれます:

  • X-Remaining-Requests: 残りの実行可能なリクエスト回数
  • X-Requests-Per-Minute: レート制限値

標準レート制限

標準レート制限は、パスレート制限と、完全一致レート制限の2つの種別に分類されます。

パスレート制限

この制限は、アクセスしているリソースのパスに応じて適用されます。例えば、 GET /stores/{store_id_1} と GET /stores/{store_id_2} というリクエストは、ストアIDが異なっていたとしても、同じパス(/stores)に対する2回のリクエストと数えられます。

  • レート制限: 1,200 リクエスト毎分
  • バーストレート: 30 リクエスト

また、APIのレスポンスには以下のヘッダが含まれます:

  • X-Remaining-Requests-Route: 残りの実行可能なリクエスト回数
  • X-Requests-Per-Minute-Route: レート制限値

完全一致レート制限

これはリソースIDやクエリ文字列も含めて完全に一致したパスに対して適用されます。例えば、PATCH /stores/{store_ID_1} というリクエストで同じストアの更新を繰り返すような場合はこの制限が適用されます。

  • レート制限: 120 リクエスト毎分
  • バーストレート: 10 リクエスト

また、APIのレスポンスには以下のヘッダが含まれます:

  • X-Remaining-Requests-Exact: 残りの実行可能なリクエスト回数
  • X-Requests-Per-Minute-Exact: レート制限値

最後に、パス レート制限と 完全一致 レート制限は同じパスに同時に作用します。例えば、異なる4つのストアを更新する場合、 完全一致 レート制限によって各ストアのパスではそれぞれ 1 リクエストと数えられますが、パス レート制限によって同じリソースに対して4回のリクエストと数えられます。

リソース制限

1つの加盟店もしくはストアで保持可能なアクティブ状態のリソースの数に制限があります。この制限を超えてリソースを作成しようとすると、ResourceLimitReached エラーとなります。制限値は以下となります:

  • ストア: 加盟店毎に 100
  • ストアレベル Webhook: ストア毎に 20
  • 加盟店レベル Webhook: 加盟店毎に 20
  • ストアレベルアプリケーショントークン: ストア毎に 20
  • 加盟店レベルアプリケーショントークン: 加盟店毎に 20
  • 銀行口座: 加盟店毎に 10
  • パスワードリセットトークン: 加盟店は1日に5回までパスワードリセットを要求できます。
  • テスト課金：一日で1440件