API usage best practices

Token Best Practices

Do not create new access tokens every time you need to perform an API call for a given tenant. Instead, re-use the access token during the 15 minutes it is valid.

Use the refresh token to renew your access instead of creating a new token.

If you don’t respect these guidelines, an https 429 rate limiting error is displayed when you try to get a new access token.

The following flowchart represents the ideal scenario for token management:

Limits

An API request cannot last more than 28 seconds. If your API call lasts longer than 28 seconds, you have two options:

• Use asynchronous execution mode. In asynchronous execution mode, you get a URL to fetch the result state until it becomes available.
• Reduce the scope of your request. For example, you can reduce the number of records you want to read or reduce the number of fields and linked nodes you want to query simultaneously.

A 6 megabite API payload limit exists in both send and receive mode. If you reach this limit, reduce the range of records and number of fields you want to include in the query.

A throttling system is in place per each tenant shared across all applications. Hence, it is possible that you get a https 429 rate limiting error when consuming GraphQL APIs. In that case, the best strategy is to implement an exponential backoff retry mechanism on your side. For instance, wait 200ms before retrying. If that does not work, wait 500 miliseconds, then 1.5 seconds, and so forth. If after several retries you still get an error, consider the request a failure.