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

# Rate limits

> See which Salesforge and Multichannel API endpoints are rate limited, and how to retry when you hit a limit.

Some Salesforge and Multichannel API endpoints limit how fast each account can call them, so that one integration cannot slow down everyone else. A request over a limit gets `429 Too Many Requests` and a `Retry-After` header that says how many seconds to wait.

## How the limits work

Limits apply to your account, not to an API key or an IP address. Every API key and integration on the account counts toward the same limits.

Each limit applies to one endpoint and has three parts:

* **Requests per minute** is the pace you can keep up.
* **Burst** is how many requests you can send at once before you have to slow down to that pace. Unused requests build back up to the burst at the per-minute rate. For example, 60 requests per minute with a burst of 10 lets you send 10 requests at once, then 1 a second.
* **Requests in flight** is how many requests can be running at the same time.

## Rate limited endpoints

These endpoints are rate limited:

| Endpoint | Requests per minute | Burst | Requests in flight |
| - | - | - | - |
| [Listing contacts](https://developer.salesforge.ai/products/salesforge/get-paginated-contacts.md) (Salesforge API): `GET /workspaces/{workspaceID}/contacts` | 60 | 10 | 2 |
| Listing sender profiles (Multichannel API): `GET /workspaces/{workspaceID}/sender-profiles` | 30 | 5 | 2 |

Salesforge API paths are relative to `https://api.salesforge.ai/public/v2`. Multichannel API paths are relative to `https://multichannel-api.salesforge.ai/public/multichannel`.

Support can set different limits for your account.

## When you hit a limit

A request over a limit gets `429 Too Many Requests`. The body says how long to wait:

```json theme={null}
{
  "message": "rate limit exceeded for this endpoint, retry after 2 seconds"
}
```

When too many of your requests are running at the same time, it reads `too many concurrent requests for this endpoint, retry after 1 second` instead.

The `Retry-After` header carries the same wait, in whole seconds. It is always at least 1.

A rejected request is not processed, so you can send it again unchanged.

## Rate limit headers

Responses from a rate limited endpoint carry three headers that describe its limit, so you can pace yourself before you hit it:

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | The burst of the limit: how many requests you can send at once. |
| `RateLimit-Remaining` | How many requests you can send right now. |
| `RateLimit-Reset` | Seconds until the limit is back to its full burst. |

A `429` for too many requests in flight carries only `Retry-After`.

## Retrying well

* Wait for `Retry-After` before you send the request again. Don't retry in a tight loop.
* Slow down when `RateLimit-Remaining` gets close to 0.
* Keep the number of requests you run in parallel below the requests in flight limit. Running more at once doesn't make you faster; the extra requests get `429`.
* Read lists with the largest page you need, and read the pages one after another. For contacts, use cursor pagination. See [Getting paginated contacts](https://developer.salesforge.ai/products/salesforge/get-paginated-contacts.md).
* Don't poll for changes by reading a whole list again and again. React to webhooks where they cover your case.

This example waits for `Retry-After` and sends the request again:

```javascript JavaScript theme={null}
async function salesforgeFetch(url, init, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(url, init);
    if (response.status !== 429 || attempt === maxRetries) {
      return response;
    }
    const seconds = Number(response.headers.get("Retry-After")) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}
```

```python Python theme={null}
import time

import requests


def salesforge_request(method, url, max_retries=3, **kwargs):
    for attempt in range(max_retries + 1):
        response = requests.request(method, url, timeout=30, **kwargs)
        if response.status_code != 429 or attempt == max_retries:
            return response
        seconds = int(response.headers.get("Retry-After", 2**attempt))
        time.sleep(seconds)
```

## Related resources

* [Getting paginated contacts](https://developer.salesforge.ai/products/salesforge/get-paginated-contacts.md)
* [Authentication](https://developer.salesforge.ai/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.