Skip to content

Knowledgebase

Handling API rate limits in a scheduled integration

development

A scheduled integration should stay within the provider’s allowed request rate and recover calmly when it is limited. Increasing the cron frequency can make a rate-limit problem worse.

What you need before you begin

Read the provider’s current limits for the relevant account and endpoint. Identify other applications sharing the same credential or quota.

01 Handle API rate limits in a scheduled integration

  1. Limit concurrency and request frequency in the integration. Share the limit across workers when they use the same provider account.

  2. Inspect rate-limit responses and documented headers. Where Retry-After is supplied, parse the supported date or delay format correctly.

  3. Pause or reschedule work instead of retrying immediately. Add bounded backoff and jitter while preserving the integration’s total retry policy.

  4. Reduce unnecessary calls through batching, conditional requests or suitable caching when the API supports them.

  5. Monitor pending work and freshness so a delayed sync is visible rather than silently appearing complete.

02 Example: reschedule a job after a 429 response

Suppose a scheduled status sync receives the following response at 09:00:00 UTC. Treat the delay as an instruction to defer work, not as a reason to retry from every worker immediately. This is a sample response for a controlled test.

Code or configuration example
HTTP/1.1 429 Too Many Requests
Retry-After: 45
Content-Type: application/json

{"error":"rate_limited"}

The earliest retry in this example is 09:00:45 UTC. Add bounded jitter where your integration permits it, and coordinate workers sharing the same account quota. The header can also contain an HTTP date, so a parser that accepts only integers is incomplete. Keep the unprocessed cursor or job state for the next attempt.

Expected result: The queue pauses without losing work, then resumes within its attempt and overall time limits. Monitoring shows the sync is delayed rather than incorrectly reporting fresh data.

Confirm the expected result

Use a test environment or controlled low-volume scenario to confirm the integration backs off and resumes without duplicate work. Check that one worker does not consume the whole shared allowance.

Troubleshoot unexpected results

If limits occur at a fixed time, compare overlapping scheduled jobs and multiple installations using the same key. Raising local timeouts does not increase the provider’s quota.

A common question

Is a 429 response the same as invalid credentials?

It generally indicates rate limiting, but follow the provider’s response details. Authentication failures and exhausted commercial quotas can have different remedies and should not be handled by identical retries.

Sources and further reading

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support