Skip to main content

Rate Limiting

HTTP Headers​

Rate limits are returned via HTTP headers.

X-Ratelimit-Bucket: general
X-Ratelimit-Limit: 60
X-Ratelimit-Remaining: 21
X-Ratelimit-Reset: 1533715145

Currently all API endpoints are subject to rate limiting. We're allowing 60 calls every 60 seconds by default. The rates are limited within the scope of the number and the message type.

The buckets that apply are:

  • general
  • text
  • media

If you exceed your rate limit allowance the HTTP API will start returning an HTTP 429 error status.

If you feel the current limits need changing for your use case, please get in touch with us.

The HTTP response from the API has the following headers set which help you monitor your usage and remaining allowance.

X-Ratelimit-Bucket

How your API call was categorized. The allowance applies per categories. The default bucket is general. API calls for sending text messages are categorised as text and API calls for sending messages with any kind of media attachment are categorised as media.

X-Ratelimit-Limit

How many calls you are allowed to make to this API endpoint on behalf of the number. Currently defaults to 60.

X-Ratelimit-Remaining

How many calls are remaining within the specified time. Currently the rate limits are reset every 60 seconds.

X-Ratelimit-Reset

The Unix timestamp in Epoch seconds when the rate limit will be reset.

These rate limits are enforced per number, not per account.

Throttling​

We have the ability to force API clients to slow down if they are not respecting the rate limit allowances configured.

If you see an HTTP response header with X-throttling: 1 then you are being throttled. Turn will keep the HTTP connection open until you are back within the rate limit allowance configured for your number.