| name | intercom-rate-limits |
| description | Handle Intercom API rate limits with backoff, queuing, and header monitoring.
Use when handling 429 errors, implementing retry logic,
or optimizing API request throughput for Intercom.
Trigger with phrases like "intercom rate limit", "intercom throttling",
"intercom 429", "intercom retry", "intercom backoff", "intercom request limit".
|
| allowed-tools | Read, Write, Edit |
| version | 1.6.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","support","messaging","intercom"] |
| compatibility | Designed for Claude Code |
Intercom Rate Limits
Overview
Intercom enforces rate limits per app and per workspace. Handle 429 errors
gracefully with exponential backoff, queue-based throttling, and proactive
header monitoring. This skill gives you five composable defenses — a retry
wrapper, a live monitor, a request queue, request batching, and metrics — so a
high-volume integration stays under the ceiling instead of spraying 429s.
The full, copy-paste TypeScript for all five lives in
references/implementation.md; this page carries
the limits, the header contract, and a lean skeleton so you can wire it up from
here and drill in for depth.
Rate Limit Tiers
| Scope | Limit | Notes |
|---|
| Private app | 10,000 req/min | Per app |
| Public app (OAuth) | 10,000 req/min | Per app |
| Workspace total | 25,000 req/min | Across all apps |
| Search endpoints | 1,000 req/min | /contacts/search, /conversations/search |
| Scroll endpoints | 100 req/min | Bulk data export |
Rate Limit Headers
Every response includes these headers — read them to throttle proactively:
X-RateLimit-Limit: <max requests per window>
X-RateLimit-Remaining: <remaining requests>
X-RateLimit-Reset: <unix timestamp when window resets>
Prerequisites
- An Intercom access token in
INTERCOM_ACCESS_TOKEN (Developer Hub > Your App
Authentication) — all requests below send it as Authorization: Bearer.
- The official SDK:
npm install intercom-client.
- For queue-based throttling:
npm install p-queue.
- Read an existing client wrapper before editing so you extend it rather
than duplicate it.
Instructions
Apply the defenses in order — each builds on the previous one. Use Write to
create a new intercom-rate-limit.ts module, or Edit to fold these into an
existing client wrapper.
-
Wrap every call in header-aware retry. On 429, wait until
X-RateLimit-Reset; on , exponential backoff with jitter. Skeleton:
