API Limits

API requests are subject two types of limits: request rate limits and resource limits. Merchants and developers should understand these limits in order to schedule their requests optimally.

In addition to this rate limitation, please note that there is a duplicate error (error code: 311) if billing is processed within 30 seconds with the same card and the same recurring token.

Rate Limits

The UnivaPay API establishes request rate limits depending on the route and resource that is being accessed. At the beginning, the merchant receives an endowment of requests that can be sent at once, called the burst rate. If this rate is exhausted, the endowment gets replenished at a certain rate, until the burst rate is fully recovered. Requests beyond the rate limit are met with a Too Many Requests error. The rate limit and the number of remaining requests can be found in the headers of each API response. Below is an example of the headers returned by the API:

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

Assume that a merchant sends requests to a route for which the limit establishes a burst limit of 100 requests and a rate of 1,200 requests per minute.

In this case, the merchant can send 100 requests at once, which exhausts its burst limit. From there, the API replenishes the merchant’s endowment at a rate of 0.02 requests per millisecond (1,200 requests-per-minute divided by 60,000 milliseconds in a minute). This means that the merchant has to wait for at least 50 milliseconds to make its next request.

If the merchant decided instead to wait for 5 seconds, he would find that he can now send 100 requests at once. The maximum number of requests that the merchant can send at once will remain at 100 even if the merchant decided to wait for more than 5 seconds.

Types of rate limits

There are two types of limits: Charge rate limits, and Standard rate limits. Routes affected by the Charge rate limits are not affected by the Standard rate limits, and vice versa.

A more detailed explanation of each type of limit is found below.

Charge Rate Limit

This limit affects the following routes:

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

The limit is defined by the following parameters:

  • Rate limit: 3000 requests per minute
  • Burst size: 100 requests
  • Headers: X-Remaining-Requests and X-Requests-Per-Minute

Standard Limits:

Standard rate limits are divided in two sub-types: Route rate limits and Exact rate limits, explained below.

Route Limit:

This limit applies to requests according to the resource that is being accessed. For example, sending a request to GET /stores/{store_id_1} and to GET /stores/{store_id_2} count as two requests made to the same resource (stores), even if the store IDs are different.

  • Rate limit: 1200 requests per minute
  • Burst size: 30 requests
  • Headers: X-Remaining-Requests-Route and X-Requests-Per-Minute-Route

Exact Limit

This applies to an exact route, including the resource ID and query strings. For example, a merchant trying to repeatedly patch the same store with a request like PATCH /stores/{store_ID_1} might eventually hit this limit.

  • Rate limit: 120 requests per minute
  • Burst size: 10 requests
  • Headers: X-Remaining-Requests-Exact and X-Requests-Per-Minute-Exact

Finally, Route and Exact limits affect the same routes at the same time. For example, patching four different stores only counts as one request for each store route in terms of the Exact limit, but counts as four requests for the same resource in terms of the Route limit.

Resource Limits

The API also sets limits to the number of resources that a single merchant or store can hold in an active status at a given point in time. Requests attempting to create resources beyond these limits are met with a ResourceLimitReached error. The limits are described below:

  • Stores: 100 per merchant
  • Store-Level Webhooks: 20 per store
  • Merchant-Level Webhooks: 20 per merchant
  • Store-Level Application Tokens: 20 per store
  • Merchant-Level Application Tokens: 20 per merchant
  • Bank Accounts: 10 per merchant
  • Password Reset Tokens: a merchant is able to request a password reset up to 5 times within one day
  • Test charge: 1440 times within one day