Working with Rate Limits

You can see the details of the specific rate limits for each Method and Entity on the Geotab SDK site here.

While limits are in “Coming Soon”, the X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset headers are set even though the server will not limit the request. This allows any consumer to observe the headers ahead of the limits being rolled out.

If using the .NET Geotab.Checkmate.Objectmodel nuget package, there is no access to the headers of the request. To facilitate testing of how your integration works with the new limits, a new optional parameter has been added to the API.cs constructor. Constructing with the optional ApiClientConfiguration with EnableRateLimitObservation set to true and run your integration The nuget package will throw an OverLimitException from the library when the returned result is over a given limit even though the server is not limiting the request.

This will give integrators the opportunity to test how their interactions will react before the limits are strictly imposed by the API.

OverLimitException

When a rate limit is exceeded, an OverLimitException error is returned. A header (Retry-After) is also set with time remaining for the limit to reset.

Header example

Headers

If a rate limit is applied to an API, with a successful JSON-RPC response, headers are set with rate limit information:

• X-Rate-Limit-Limit: the rate limit period (eg. 1s, 1m, 12h, 1d)
• X-Rate-Limit-Remaining: number of request remaining
• X-Rate-Limit-Reset: UTC date time (ISO 8601) when the limit resets

Tiers refers to the number of tracked assets managed by a database. This includes only devices that have hardware reporting active data into MyGeotab including the Go Device, Go Anywhere, and Custom Telematics devices.

The following public endpoints are excluded from tiered rate limits, and will always have a fixed base limit:

• Authenticate
• CreateDatabase
• SetUserPassword
• DeviceShare

Use the MyGeotab API Adapter

The MyGeotab API Adapter solution serves as both an example of proper integration via data feeds and the potential foundation for those seeking to develop new integrations with the Geotab platform. Essentially, it uses data feeds to pull the most common data sets from a MyGeotab database and stream the data into tables within a SQL Server, PostgreSQL or Oracle database.

Read more about it here.

Get vs GetFeed

It is preferred to use GetFeed instead of a Get call for an entity which supports it.

Wait logic between calls

A straightforward solution can be introducing wait times between subsequent calls. It is suggested that ensuring at least 1010 milliseconds has elapsed between calls.

The general strategy for handling rate limits requires the integrator or partner to implement an error handler in code that recognizes rate limit errors and pauses requests until the limit resets. This will prevent your app from continuously trying to make requests once the rate limit is hit.

Using exponential backoff

Exponential Backoff is an essential error-handling strategy in network applications. In this method, a client will retry a failed request after waiting for an increasing amount of time before each retry.

When a request fails due to rate limiting, the client waits for a predetermined period before retrying the request. If the request fails again, the client waits longer for the next attempt, and this process continues up to a maximum delay limit. This approach helps to prevent frequent hits to the rate limit and reduces the load on the server.

JavaScript example implementation

Below is an example of how you might currently be making API calls:

To handle rate limits effectively, you can wrap your base function with exponential backoff logic. The following steps outline this process:

1. Set the Maximum Number of Attempts
2. Calculate the Exponential Delay
3. Try the Call
4. Catch the OverLimitException
5. Wait for the Delay
6. Repeat steps 1-5 until either the maximum number of attempts is reached, any other error is thrown, or results are successfully returned.

Here is an example implementation:

This function could be used within a try-catch block to handle any resultant errors: