Rate limits

The Synthesio API enforces rate limits to ensure fair usage and reliable performance. Each request you make counts against two independent quotas:

  1. Hourly bandwidth: The total amount of data you can download per hour.
  2. Hourly hits: The total number of API requests you can make per hour.

Both are measured over a one-hour sliding window (that is, the past 60 minutes).

If either limit is reached, the API stops processing requests and responds with a 429 Too Many Requests status code until usage falls below the limit again.

Allowance#

Contact your account manager or support team to understand your specific rate limit allowance.

Rate-limit headers#

To allow you to better keep track of your usage, the API includes the following HTTP headers in each response:

  • x-hourly-bandwidth: The current bandwidth usage for the past hour (in bytes).
  • x-hourly-hits: The current number of API requests made in the past hour.
  • x-max-hourly-bandwidth: The maximum allowed hourly bandwidth (in bytes).
  • x-max-hourly-hits: The maximum number of API requests allowed per hour.

For example, if you are granted 1,200 calls per hour and 200 MiB per hour, a response might include the following headers:

x-hourly-bandwidth: 40193228
x-hourly-hits: 295
x-max-hourly-bandwidth: 209715200
x-max-hourly-hits: 1200

This means that you have made 295 calls and retrieved roughly 40 MB over the past hour.

Avoiding rate-limit errors#

To avoid hitting the rate limits, you can:

  • Implement a short delay between consecutive API requests to reduce the rate at which you consume your allowance.
  • Implement exponential backoff before retrying failed requests, and stop retrying after a certain number of attempts.
  • Optimize your API usage by reducing unnecessary requests and retrieving as much data as allowed in each request.