Rate limits

The budget

Requests to the Developer API are counted per API key in a fixed one minute window, with one budget:

Applies to	Default
Every request (all are `GET`)	120 requests per minute

One budget, because this version only reads. When write endpoints arrive they will get their own, much lower, ceiling: a read loop is cheap and integrations legitimately do a lot of it, while a write loop creates rows. The budget belongs to the key, not to your user or your organization. Two keys in one organization each get their own, which is what lets you isolate a batch job from your live integration by giving it its own key.

The unversioned payment-acceptance endpoints (/one-time-payment, /payment-intent, /payment-method) are not metered by this mechanism. The limit above applies to /api/developer/v1 only.

Reading your remaining budget

Every Developer API response carries the current state, including successful ones, so you can slow down before you are cut off rather than after.

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the window for this budget
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Seconds until the window rolls over and the full budget returns

When you exceed it

The API answers 429 with a Retry-After header, in seconds:

{
  "message": "Rate limit exceeded. Retry in 43 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Requests that receive a 429 still count against the window. A client that keeps hammering after being throttled keeps its own window alive rather than getting a fresh budget the moment the old one lapses. Honour Retry-After.

Backing off correctly

Wait for Retry-After, then add a little randomness so that several workers throttled at the same moment do not all return at the same instant.

async function compagoRequest(url, options, attempt = 0) {
  const res = await fetch(url, options);

  if (res.status !== 429 || attempt >= 5) return res;

  const retryAfter = Number(res.headers.get('retry-after') ?? 60);
  // Jitter, so a fleet of workers throttled together does not return together.
  const waitMs = retryAfter * 1000 + Math.random() * 1000;

  await new Promise(resolve => setTimeout(resolve, waitMs));
  return compagoRequest(url, options, attempt + 1);
}

import random, time, requests

def compago_request(method, url, api_key, attempts=5, **kwargs):
    headers = {"x-api-key": api_key, **kwargs.pop("headers", {})}

    for attempt in range(attempts):
        res = requests.request(method, url, headers=headers, timeout=30, **kwargs)
        if res.status_code != 429:
            return res

        retry_after = int(res.headers.get("Retry-After", 60))
        # Jitter, so a fleet of workers throttled together does not return together.
        time.sleep(retry_after + random.random())

    return res

Staying well under the limit

Filter server side, do not page and discard

Fetching every payment to keep the ten you wanted spends your whole budget on rows you throw away. GET /developer/v1/payment accepts status, date bounds and the id of the payment link, subscription or saved card the payment came from. See Pagination.

Raise limit instead of making more requests

One request for 100 rows costs one unit of budget. Ten requests for 10 rows cost ten. limit=100 is the maximum.

Poll on a schedule, not in a loop

Nothing in a payments system changes fast enough to need second-by-second polling. Ask for what changed since your last run with createdAtFrom, on a cadence measured in minutes.

Use a separate key for batch work

Because the budget is per key, a nightly export running on its own key cannot throttle the key another integration depends on. Create keys in the dashboard under Configuraciones, then Desarrollador.

Requesting a higher limit

If a legitimate workload does not fit the defaults, contact us with your key name, the endpoints involved and the request rate you need. The limits are configured per environment and can be raised.

Get Started

Core Concepts

Developer API

Accept Payments

Integrations

The budget

Reading your remaining budget

When you exceed it

Backing off correctly

Staying well under the limit

Requesting a higher limit

​The budget

​Reading your remaining budget

​When you exceed it

​Backing off correctly

​Staying well under the limit

​Requesting a higher limit

The budget

Reading your remaining budget

When you exceed it

Backing off correctly

Staying well under the limit

Requesting a higher limit