> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> How Paygentic counts your requests, which endpoints have a limit, and how to retry after a 429 response.

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

| Endpoint                                      | Limit            | Bucket       |
| --------------------------------------------- | ---------------- | ------------ |
| `GET /v0/customers`                           | 60 per 6 seconds | Merchant     |
| `POST /v0/subscriptions/{id}/reconciliations` | 2 per second     | Subscription |
| `POST /v0/subscriptions/{id}/portal`          | 1 per second     | Subscription |
| `POST /v2/invoices/lineItems`                 | 60 per minute    | Merchant     |
| `GET /v0/costs/report`                        | 600 per minute   | Merchant     |
| `GET /v0/integrations/salesforce/accounts`    | 30 per minute    | Merchant     |

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.

| Header                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `x-ratelimit-limit`     | The limit for this bucket.                      |
| `x-ratelimit-remaining` | The requests you can still send in this window. |
| `x-ratelimit-reset`     | The seconds until the window resets.            |

A `429` response adds one more header:

| Header        | Meaning                                                |
| ------------- | ------------------------------------------------------ |
| `retry-after` | The seconds to wait before you send the request again. |

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:

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please wait before trying again."
}
```

## 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.

## Related pages

* [Authentication](/authentication) — How to send your API key
* [API Keys](/api-keys) — How to create and revoke keys
* [Reconciling subscription features](/platform/billing/reconciling-subscription-features) — The reconciliation endpoint and its limit