What API rate-limit protections should we build before launching a new integration with Freshsales?

You will certainly want to bake in a good API rate-limit protection before you roll out some new integration with Freshsales, as Freshsales applies a high-rate throttle on a per-user and per-organization basis to stop abuse. The aim is to ensure that you are making your integration strong and not merely compliant in that it can withstand bursts without collapsing syncs or workflow.

The following is the most appropriate configuration: begin with client-side throttling, which limits outgoing requests per access token or user. The REST API of Freshsales usually supports about 50 requests per minute per user, and it is always safe to dynamically scale according to the HTTP 429 Too Many Requests response. Always read and obey the Retry-After header Freshsales will reply with - that is what your integration should wait before trying again.

Add exponential backoff with jitter (random delay) in case two or more clients reach the limit simultaneously, they do not all backoff at the same time. On the server side, keep per-tenant quotas so that a single noisy user does not drown out all the other users. In the bulk cases (e.g. contact imports or deal syncs), submit a request to the queue and process in an asynchronous, small-batch (e.g. 100 records) way rather than hammering the API at the same time.

Lastly, measure and keep a record of all this: request success rate, average latency, throttle events and retry success rate. Send those measures to your monitoring stack (Datadog, Prometheus or CloudWatch) in order to adjust limits before Freshsales imposes them. To take it a step further, include a circuit breaker which halts non-critical syncs during throttling spikes. Concisely - think stream, not deluge. That is how you roll out an integration which scales well without being rate-limited into nothingness.