API Rate Limit Handling for SaaS Connectors

Every SaaS API limits how much you can ask of it. Exceed the limit and requests start failing, syncs fall behind and, in the worst cases, the provider blocks your integration for a while. Good API rate limit handling is what separates a connector that quietly copes with busy days from one that fails every month end. It means knowing how each API signals its limits, pacing requests to stay under them, backing off correctly when they are hit, and planning quota before growth turns a comfortable margin into a daily problem. This guide explains each of those steps for custom SaaS connectors.

How SaaS APIs signal their limits

Limits come in several shapes, often at once:

• Requests per time window, such as per minute, hour or day
• Concurrent requests, limiting how many calls can be in progress at once
• Cost-based limits, where expensive operations use more of the allowance
• Per-user, per-app or per-account limits
• Secondary or abuse limits that trigger on bursts even when the main allowance remains

APIs usually tell you where you stand through response headers and status codes. GitHub's documentation on REST API rate limits is a clear example. It returns headers such as x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used and x-ratelimit-reset, which gives the time the current window resets in UTC epoch seconds. When a secondary limit is exceeded, it returns a 403 or 429 response; if a retry-after header is present, clients should wait that many seconds before retrying.

The HTTP status 429 Too Many Requests is the standard signal, but some APIs use 403, 503 or a custom error body. Read each provider's documentation and record exactly how it signals limits.

Pace requests before you hit the limit

The best rate limit is the one you never hit. Pacing strategies:

• Read the remaining-allowance headers on every response and slow down as the number falls
• Use a client-side limiter, such as a token bucket, set below the documented limit to leave headroom
• Limit concurrency, so a pool of workers cannot fire hundreds of calls at once
• Spread scheduled jobs across the hour instead of starting everything at the top of it
• Share one limiter across all workers and processes that use the same credentials, since the provider counts them together

Headroom matters because other tools, such as a native integration or a user's browser session, may use the same allowance.

Back off correctly when limits are hit

When a limit response arrives:

1. Stop sending new requests with those credentials.
2. If the response includes Retry-After or a reset time, wait at least that long.
3. If not, wait a sensible minimum and increase the wait on each repeated failure. GitHub's documentation, for example, advises waiting at least one minute when no other guidance applies, then waiting for exponentially increasing periods and throwing an error after a specific number of retries.
4. Add a little random jitter to waits, so many workers do not retry at the same instant.
5. Resume at a slower pace, not at full speed.

Retrying immediately in a tight loop is the worst response: it wastes allowance and can lead to longer blocks. GitHub warns that continuing to make requests while rate limited may result in the integration being banned.

Reduce the calls you need

Often the cheapest fix is fewer calls:

• Use bulk or batch endpoints where available, sending many records per request
• Request only changed records, using "modified since" filters or change feeds
• Use webhooks for change notification instead of frequent polling
• Cache reference data, such as users, products or picklist values, instead of fetching it repeatedly
• Ask for only the fields you need, if the API supports field selection
• Increase page sizes to the maximum the API allows

Our guide to Zoho CRM API limits shows how these techniques apply to one widely used CRM.

Worked example: API rate limit handling rules for one connector

The table below shows hypothetical rules for a connector that syncs orders and customers with a SaaS platform. Limits, thresholds and timings are illustrative and would come from the provider's documentation and your own monitoring.

SituationSignalConnector behaviourNormal operationRemaining allowance above 30%Full pace, up to 5 concurrent requestsAllowance running lowRemaining below 30%Drop to 2 concurrent requests, defer low-priority jobsAllowance nearly goneRemaining below 5%Pause non-urgent work until reset timeLimit hit with Retry-After429 with Retry-AfterWait the given seconds plus jitter, resume at half paceLimit hit without guidance429 or 403 limit errorWait 60 seconds, then double on each repeat, stop after 5 triesRepeated failures5 consecutive limit errorsAlert the owner, move items to a review queue

Writing rules down like this makes the behaviour testable and gives the team a shared reference when the connector misbehaves.

Prioritise work when quota is tight

Not every call is equally urgent. Separate work into priority levels:

• High: actions users or customers are waiting for, such as a new order reaching the ERP
• Medium: regular syncs that can tolerate some delay
• Low: backfills, reports and bulk updates

When allowance runs low, the connector should keep high-priority work flowing and defer the rest. Queues per priority level make this straightforward.

Plan quota for growth

Rate limits become a problem gradually, then suddenly. Track:

• Daily and peak-hour API usage against each limit
• Growth in records and events over recent months
• The share of usage taken by each job or integration

Project forward from these trends. If peak usage will exceed a comfortable share of the limit within the next few months, act early: optimise calls, move to bulk endpoints, spread jobs, or ask the provider about higher limits or plan upgrades. Many providers offer higher limits on higher plans or on request, but approval and changes can take time.

Failover and degraded modes

If an API becomes unavailable for longer, decide in advance how the connector behaves. Queue changes durably so nothing is lost, show users that a sync is delayed rather than silently stale, and process the backlog at a controlled pace once the API recovers. Our guide to handling OCR API rate limits describes similar queueing and failover patterns in a document processing context.

Frequently Asked Questions

What is API rate limit handling?

It is how an integration stays within an API's usage limits: reading limit signals, pacing requests, backing off correctly when limits are hit and reducing unnecessary calls.

What should a connector do when it gets a 429 response?

Stop sending requests with those credentials, wait for the Retry-After period or reset time if given, otherwise wait and increase the delay on each repeat, then resume more slowly.

How can we reduce API calls in a SaaS integration?

Use bulk endpoints, request only changed records, rely on webhooks instead of frequent polling, cache reference data and use the largest page sizes allowed.

When should we ask a provider for higher limits?

When usage trends show you will regularly approach the limit even after optimising, and well before the limit becomes a daily problem, since changes can take time.

Keep connectors within their limits

We build and tune SaaS connectors with pacing, backoff, prioritised queues and quota monitoring. See our CRM and API integration services, or talk to us about API rate limits.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.