# rate limits

## API rate limits

All calls to the API are allotted a specific number of requests per refresh period. Our rate limits depend on if you're an individual or project, as well as what environment of ours you are targeting. If you're a partner, your limit is determined by your project. Otherwise, your limit is determined on a per-IP-address basis.

We set the limits based on an analysis of the last quarter's traffic and review and update this quarterly. Once this threshold has been reached, we will return a status code `429` response.

Integrations with the API that do not contain an api-key (see below for an example), must not exceed 5 requests per second, per-IP-address. This is measured across all endpoints of the API.

### Integration[​](https://docs.x.immutable.com/docs/x/api-rate-limiting#integration) <a href="#integration" id="integration"></a>

To have a higher rate limit, you will need to obtain an API key to use with all of your calls to our API. It also uniquely identifies your company project and should not be shared.

If you haven’t already, <mark style="color:blue;">register your project with us</mark>. This will provide you with a numeric project ID. To obtain an API key, <mark style="color:blue;">please contact support</mark> and quote your project ID. We'll evaluate if a higher rate limit with an API key can be granted.

INCREASING YOUR RATE LIMIT

In the majority of applications a higher rate limit does not improve the usability of your application. Consider how frequently trades or mints are happening and how that impacts the user experience. Caching of data can be a great way to help you manage bursts of high traffic on your application and minimise your network load. This can also create a better user experience.

The API key must be added to all calls to our API in the http header:

```
curl -is 'https://api.x.XpansionChain.com/v1/orders/1337' --header 'x-api-key: xxx'
```

### Best practices[​](https://docs.x.immutable.com/docs/x/api-rate-limiting#best-practices) <a href="#best-practices" id="best-practices"></a>

Here are some best practices to follow for a successful integration:

* **Limit your clients** - Proactively limiting your outgoing call rate will prevent you from being externally rate-limited and overall encourage you to handle those cases in which you are limited more gracefully. Additionally, if you build your clients with this logic then you can also sub-divide your aggregate limit more granularly (as appropriate for your project) so that none of them consume too much quota. For example, you might choose to subdivide your total limit by country, region or other.
* **Retry and back-off** - When you are rate-limited, retry your requests after waiting some time. Use an <mark style="color:blue;">exponential backoff</mark> to progressively increase this wait time.
* **Avoid polling** - Polling our API (especially "short polling", in which you do not wait for a response) is an anti-pattern and will quickly consume your quota.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xpansionchain-1.gitbook.io/xpansionchain/troubleshooting/api/rate-limits.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.