When an app calls the API and receives an HTTP status code of 429, it means their application has exceeded its assigned rate limit. Rate limits exist to protect the platform from abuse - both intentional and unintentional. A rate limit basically says, "a user can call this API endpoint this many times in this time period." If that limit is exceeded, then you receive this error.
You can learn more about rate limits, and learn how to be alerted to the risk of being rate limited prior to the platform temporarily blocking access to the API in our Developer Guide.
So how do you resolve being rate limited?
The most straight-forward solution is to get your app to slow down on how many times it is calling the API. Of course, that is easier said then done, and it is beyond the scope of this article to discuss all the ways to do this architecturally, but consider the following:
Implement a queuing, or job/worker system of some kind. Using a queue, you can place requests to send SMS, and then process those requests at a rate that keeps you below your limit.
Follow best practices by inspecting HTTP response headers that include details about how many requests you can still make before being rate limited.
Implement artificial delays in your code. This is not an ideal solution by any stretch, but it can solve the problem, especially in the short term.
There are circumstances however under which architectural changes will still not address your application's need to call the API a great deal. If this is the case for you, then you can file a help ticket with the Developer Support team to request a different rate limit be applied to your application.
If you elect to take this path, be prepared to tell support about your application, its API call volume requirements, its growth potential, and the steps you have already taken to mitigate rate limit issues. Support will work with you to find the right rate limit for your app. It will be a carefully tailored limit. And in case you were wondering - there is no option to remove rate limits all together.
Common rate limit circumstances
A common scenario in which apps trigger a rate limit relates to authentication. Developers will often implement retry logic for failed auth. If something has happened to a user's credentials or their standing as a user in the system, then no amount of retrying will fix the problem. Yet, our code doesn't know that, so it enters a loop in which auth is tried, re-tried over and over in quick succession.
More specifically this happens for apps utilizes the now-deprecated password grant flow, and the password they have stored for a user has changed, or the user itself has been deactivated. This often happens without the app knowing, and so when the app attempts to authenticate it fails, and then enters a retry loop that then triggers the rate limit.
You can see if this applies to you by logging into the Developer Console, selecting the app seeing the error and viewing the app's Analtyics tab. View API calls by Endpoint, and if you see errors associated with the authorize endpoint, then you know your culprit.
In this situation, you may need to implement a more resilient refresh token methodology, or use JWT auth instead.
