Rate limits

Each API key has a rate limit, counted by the gateway in front of the API. It is currently 600 requests a minute per key, counted over fixed one-minute windows.

The limit headers

Answers carry three headers:

• X-RateLimit-Limit: the number of requests a window allows.
• X-RateLimit-Remaining: how many are left in the current window.
• X-RateLimit-Reset: the number of seconds until the window resets.

When you exceed it

The gateway answers 429 rate_limit_exceeded. The body is the usual error object, with the type rate_limit_error. Its request_id is null: the request never reached the API.

The gateway also protects the platform against bursts from one IP address. That protection can answer 429 too, without the X-RateLimit-* headers. It counts every application behind the same IP address together, whatever their keys. Act on the status and back off the same way.

Backing off

1. Wait for the number of seconds given by X-RateLimit-Reset.
2. Retry. If you get another 429, wait longer each time: an exponential backoff, with some randomness so your workers do not retry together.

Staying under the limit

• Spread large synchronisations over time rather than sending them in one burst.
• Use limit=100 on lists: one request returns up to 100 objects.
• Walk lists forward with starting_after: it is also the cheapest call. See Pagination.
• Use one key per application, so one application’s burst does not slow another.