intercom api 429 rate limit exceeded

TL;DR

A 429 is a speed limit, not an error. Intercom returns rate-limit headers on every response, including how many requests remain and when the window resets. The fix is exponential backoff with jitter, honoring the Retry-After value when present, and moving bulk work off the request path. Do not retry immediately in a tight loop; that is how a 429 becomes an outage.

The query

intercom api 429 rate limit exceeded

Use this when

• Intercom endpoints return 429 during syncs or imports
• A job fails halfway through with rate limit errors
• Polling plus webhooks together burn through quota

Not for

• 401 unauthorized (bad credential, not a limit)
• 404 not found on a contact or conversation
• Webhook events not arriving at all

Steps

1. Read the rate-limit headers on a clean request

Make one request and inspect the rate-limit headers in the response: remaining requests, the reset timestamp, and any Retry-After value. These numbers are your pacing budget. Log them so you stop guessing.

Expected output: the exact remaining count and the reset time for your app.

2. Add exponential backoff with jitter

On a 429, wait Retry-After seconds if present, otherwise wait 2^attempt seconds plus random jitter, then retry. Cap retries at five. Jitter keeps a fleet of workers from retrying in lockstep.

Expected output: a single 429 followed by a successful retry within the backoff window.

3. Move bulk work to background queues

Contact syncs, conversation exports, and bulk updates belong in a queue with a fixed worker concurrency, not in request handlers. Size the worker count so peak throughput stays under the limit with headroom.

Expected output: a full sync completing with zero 429s.

4. Cut polling; prefer webhooks

If you poll conversations or contacts on a timer, replace it with webhook events where the data exists. Polling is the most common quota burn because it keeps firing when nothing changed.

Expected output: measured API calls per hour dropping with no loss of freshness.

5. Serialize the hottest endpoints

Conversation message sends and contact updates share quota. If one endpoint dominates, give it its own queue with its own pacing instead of letting it starve everything else.

Expected output: no endpoint starving the others; 429s gone from logs.

Variant phrasings

intercom api rate limit headers

Step 1 covers the exact headers to read and log.

intercom sync job keeps hitting 429

Steps 2 and 3 together: backoff for the spikes, a paced queue for the baseline.

Why it happens

Intercom limits per app, not per endpoint, so every poller, sync job, and request handler draws from one bucket. Teams usually discover this when the third integration goes live and the total finally exceeds the limit. The limit is fixed; the fix is always pacing, never more retries.

Edge cases

• Burst traffic after deploys: warm caches and batch the first sync instead of replaying everything at once.
• Shared app credentials: if multiple services use the same Intercom app key, their usage adds up. Split apps or coordinate budgets.
• Intercom raises limits on request for some plans; still implement backoff first, then ask.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst0jXxDGKHySjZb4tEaK5lA