Best practices for Bandwidth rate limits

Even with the most robust systems, there are bound to be rate limits. Most of the people using Catapult, one of Bandwidth’s communications APIs will never bump up against the limit. However, if you make a lot of requests in a short period of time, you may hit our rate limit. After reaching the limit, Catapult will stop processing your requests and return an error.

Outbound messages are sent OUT/DeQueued at a rate of 1 per second per number and 40 per second per account

Catching Errors caused by rate limiting

Your code should be setup to catch any errors when making an HTTP request to the Catapult API. Catapult returns a 403: Forbidden error specifying the type of error in the response body.

The same type of error is returned when exceeding the call rate limit.

Check the error code table to ensure you’re keying off the correct error

To ensure that your message or call is completed, wait the specified sample period before retrying request.

The following pseudocode shows a basic way to catch and retry rate limited errors.

Hitting the rate limit often?

If you find yourself regularly hitting Catapult’s rate limits, consider throttling your requests. Throttling is a process that regulates the rate of your requests so that they’re spread more evenly over time.

There are a few pre-built packages available for most popular programming languages. A decent example for Node is the throttled-request package.

Need more throughput?

If throttling is not a viable option or you are consistently pushing the limits of our API. Reach out to [email protected] or open a support ticket. There is a good chance we can increase your throughput!