Skip to main content
Some Paygentic endpoints limit how many requests you can send in a period of time. The table below gives every limit that the API reference documents. A small number of endpoints outside the reference also have a limit. If you call one of them, use the retry-after header on a 429 response.

​
What a limit counts

Each rate-limited endpoint counts your requests in a bucket. A bucket holds one count for one merchant on one endpoint. When the count goes above the limit, the API rejects the request with 429 Too Many Requests until the window resets. Two rules follow from this:
  • The allowance belongs to the merchant, not to the API key. If you create a second API key, your allowance stays the same. It also does not matter which of your keys a request uses.
  • Each endpoint has its own bucket. Requests to one endpoint do not spend the allowance of another endpoint.
Two endpoints count per subscription instead. For these, each subscription has its own bucket, so work across many subscriptions is not limited in total:
  • POST /v0/subscriptions/{id}/reconciliations
  • POST /v0/subscriptions/{id}/portal
Requests that the Paygentic dashboard sends on your behalf do not use your buckets. The dashboard has one shared allowance for each endpoint. Paygentic does not divide that allowance per merchant.

​
The limits

A published limit can go up later. It does not go down.

​
Response headers

An authenticated request to an endpoint in the table above returns three headers. They give the count of your bucket. A request that fails authentication returns none of them, because the API refuses the request before it counts it. A 429 response adds one more header: Endpoints outside the table can also return the three x-ratelimit-* headers. Their values do not describe a limit that you can reach. Read these headers only for the endpoints in the table. The body of a 429 response has this shape. The message text is specific to the endpoint:

​
How to retry

Do not retry a 429 immediately. An immediate retry makes the burst larger.
  1. Read the retry-after header. Wait that number of seconds.
  2. If the header is absent, wait one second. Then double the wait for each further rejection.
  3. Stop after five attempts. Then report the failure.
To stay below the limit, read x-ratelimit-remaining. Send fewer requests before it reaches 0. For bulk work, send the requests in sequence, not at the same time.