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.

https://gist.github.com/dtolb/cea32c819acea06c236beabe5022ae29#file-rate-limit-md

https://gist.github.com/dtolb/cea32c819acea06c236beabe5022ae29

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.

https://gist.github.com/dtolb/1d081f902ce993de113ed9b1b800bd1c

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

https://gist.github.com/dtolb/74088788ab25e8649a719dbc5c36c4a9

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

https://gist.github.com/dtolb/2412d7f1a57c04f8d1f87dac42e6fbef

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.

https://gist.github.com/dtolb/0cae32747e127af922fccd686e74f034

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 openapi@bandwidth.com or open a support ticket. There is a good chance we can increase your throughput!