API rate limiting

All users of our API are subject to 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.

Integration

If you are a partner company project you will need to obtain an API key to use with all of your calls to our API. It uniquely identifies your company project and should not be shared.

If you haven’t already, register your project with us. This will provide you with a numeric project ID. To obtain an API key, get in touch with us and quote your project ID.

The API key must be added to all calls to our API:

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

Best practice

Here’s some advice for 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 exponential backoff 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.

Did this page help you?