Skip to content
Skills Library
Programming · Building & coding

intercom-rate-limits

/intercom-rate-limits

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".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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".

Triggers from the description

intercom rate limitintercom throttlingintercom 429intercom retryintercom backoffintercom request limit
Original author 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".

How it works

  1. Overview
  2. Rate Limit Tiers
  3. Rate Limit Headers
  4. Prerequisites
  5. Instructions
  6. Output
  7. Error Handling
  8. Examples
  9. Resources
  10. Next Steps
Original SKILL.md headings · 131 lines, 710 words
SKILL.md preview
---
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](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.

1. **Wrap every call in header-aware retry.** On `429`, wait until
   `X-RateLimit-Reset`; on `5xx`, exponential backoff with jitter. Skeleton:

   ```typescript
   async function withRateLimitRetry<T>(op: () => Promise<T>): Promise<T> {
     // On 429: delay = (X-RateLimit-Reset * 1000) - Date.now() + 1000
     // On 5xx: delay = baseDelay * 2^attempt + jitter, capped at maxDelayMs
   }
   ```

2. **Add a proactive monitor.** Feed response headers into a monitor and call
   `waitIfNeeded()` before firing when usage crosses ~90%, so you slow down
   *before* a 429.
3. **Throttle with a queue.** Route requests through a `p-queue` capped at
   ~150 req/s to keep bursts under the per-app ceiling.
4. **Batch to cut request count.** Replace N individual lookups with OR-batched
   `contacts.search` queries.
5. **Emit metrics.** Log `remaining`, `usage_percent`, and `ms_until_reset` so
   you can alert before saturation.

Full implementation for every step:
[references/implementation.md](references/implementation.md).

## Output

Wiring these in yields three concrete artifacts in your integration:

- **A resilient client wrapper** — every call routed through
  `withRateLimitRetry` + `queuedRequest`, so transient 429/5xx are absorbed
  automatically instead of surfacing as failures.
- **Proactive throttling** — the monitor pauses outbound traffic before the
  window is exhausted, converting hard 429s into short, controlled waits.
- **Observability** — structured `intercom.rate_limit` metrics (remaining,
  usage percent, ms-until-reset) ready for dashboards and alerts.

## Error Handling

| Scenario | Strategy | Implementation |
|----------|----------|----------------|
| 429 with reset header | Wait until reset | Parse `X-RateLimit-Reset` |
| 429 without headers | Exponential backoff | 1s, 2s, 4s, 8s, 16s |
| Approaching limit (>90%) | Proactive throttle | Check remaining before request |
| Bulk operations | Queue-based | `p-queue` with `intervalCap` |
| Multiple apps hitting workspace limit | Coordinate | Shared rate limit monitor |

## Examples

**Absorb a burst of contact lookups.** Fan out hundreds of `contacts.find`
calls without tripping the limit by routing each through the queue + retry
wrapper:

```typescript
const contacts = await Promise.all(
  userIds.map(id =>
    queuedRequest(() => client.contacts.find({ contactId: id }))
  )
);
```

**Precise wait on a 429.** When a response carries `X-RateLimit-Reset`, wait
exactly until that epoch (plus a 1s buffer) instead of guessing a backoff — see
Step 1 in [references/implementation.md](references/implementation.md).

**Batch email lookups.** Replace 100 single-contact requests with 10 OR-batched
searches — full `findContactsByEmails` helper in
[references/implementation.md](references/implementation.md).

## Resources

- [Rate Limiting](https://developers.intercom.com/docs/references/rest-api/errors/rate-limiting)
- [Pagination](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination)
- [p-queue](https://github.com/sindresorhus/p-queue)
- [Full implementation](references/implementation.md) — the five defenses in copy-paste TypeScript

## Next Steps

Rate limiting is one layer of a hardened Intercom integration. Once retries and
throttling are in place, pair them with `intercom-common-errors` for full
status-code triage, and `intercom-security-basics` for token scoping and
webhook-signature verification.
Files in this package (2)
  • SKILL.md 6 KB
  • references/implementation.md 5 KB

Versions

The database has no other skills named intercom-rate-limits.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 0d6f57502ea1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100figma-rate-limits
    Handle Figma REST API rate limits with exponential backoff and request queuing. Use when encountering 429 errors, implementing retry logic, or optimizing API request throughput for Figma. Trigger with phrases like "figma rate limit", "figma throttling", "figma 429", "figma retry", "figma backoff".
  • 100instantly-rate-limits
    Implement Instantly rate limiting, backoff, and idempotency patterns. Use when handling rate limit errors, implementing retry logic, or optimizing API request throughput for Instantly. Trigger with phrases like "instantly rate limit", "instantly throttling", "instantly 429",…
  • 100lokalise-rate-limits
    Implement Lokalise rate limiting, backoff, and request queuing patterns. Use when handling rate limit errors, implementing retry logic, or optimizing API request throughput for Lokalise. Trigger with phrases like "lokalise rate limit", "lokalise throttling", "lokalise 429",…
  • 100groq-rate-limits
    Implement Groq rate limiting, backoff, and idempotency patterns. Use when handling rate limit errors, implementing retry logic, or optimizing API request throughput for Groq. Trigger with phrases like "groq rate limit", "groq throttling", "groq 429", "groq retry", "groq backoff".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.