---
name: intercom-common-errors
description: 'Diagnose and fix Intercom API errors by HTTP status code and error type.

  Use when encountering Intercom errors, debugging failed API requests,

  or troubleshooting integration issues.

  Trigger with phrases like "intercom error", "fix intercom",

  "intercom not working", "debug intercom", "intercom 401", "intercom 429".

  '
allowed-tools: Read, Grep, Bash(curl:*)
version: 1.6.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- support
- messaging
- intercom
compatibility: Designed for Claude Code
---
# Intercom Common Errors

## Overview

Quick reference for diagnosing and fixing Intercom REST API errors by HTTP
status code. Every Intercom error returns the same envelope, so triage is
fast: read the `errors[].code`, match it to the table below, apply the fix.

All Intercom errors share this shape:

```json
{
  "type": "error.list",
  "request_id": "req_abc123",
  "errors": [{ "code": "unauthorized", "message": "Access Token Invalid" }]
}
```

The full per-code catalog (causes + copy-paste fixes) lives in
[references/error-reference.md](references/error-reference.md).

## Prerequisites

- An Intercom access token in `INTERCOM_ACCESS_TOKEN` (Developer Hub > Your App > Authentication).
- `curl` and `jq` for the diagnostic commands.
- For the TypeScript fixes: the `intercom-client` SDK (`npm install intercom-client`).

## Instructions

1. **Capture the error.** Grab the HTTP status and the JSON body. Use **Read** on your app logs, or **Grep** the codebase for the failing call site to see how the request is built.
2. **Match the code.** Find the `errors[].code` in the Error Handling table below.
3. **Confirm the token/limits first.** Run the diagnostic script in [references/diagnostics.md](references/diagnostics.md) to rule out auth and rate-limit issues in one shot.
4. **Apply the fix.** Open [references/error-reference.md](references/error-reference.md), jump to your status code, and use the causes + fix snippet there.
5. **Retry only retryable errors.** 429 and 5xx are retryable with backoff; 4xx client errors are not — fix the request instead.

Fast auth check:

```bash
curl -s https://api.intercom.io/me \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  -H "Accept: application/json" | jq '.type'
# Returns "admin" when the token is valid
```

## Output

You resolve the request into one of three outcomes:

- **Fixed request** — a corrected token, added OAuth scope, valid payload, or existence check that makes the call succeed.
- **Backoff-and-retry** — for 429 / 5xx, a retry wrapper that respects `X-RateLimit-Reset` and exponential backoff.
- **Escalation** — for persistent 5xx, the `request_id` to hand to Intercom support along with the status-page state.

## Error Handling

| Error Code | HTTP | Retryable | Action |
|------------|------|-----------|--------|
| `unauthorized` | 401 | No | Regenerate token |
| `forbidden` | 403 | No | Add OAuth scope |
| `not_found` | 404 | No | Verify resource ID |
| `conflict` | 409 | No | Search before create |
| `parameter_invalid` | 422 | No | Fix input data |
| `rate_limit_exceeded` | 429 | Yes | Backoff and retry |
| `server_error` | 500+ | Yes | Retry, check status page |

**Limits:** 10,000 req/min per app, 25,000 req/min per workspace. On 429,
read `X-RateLimit-Reset` and wait until that epoch before retrying.

## Examples

**401 — invalid token.** The auth check returns nothing instead of `"admin"`. Regenerate the token in Developer Hub and update the app's env. Full walkthrough: [references/error-reference.md](references/error-reference.md).

**409 — duplicate contact.** `create` fails because the `email`/`external_id` already exists. Search first, then create:

```typescript
const existing = await client.contacts.search({
  query: { field: "email", operator: "=", value: email },
});
return existing.data.length > 0
  ? existing.data[0]
  : client.contacts.create({ role: "user", email, externalId });
```

**429 — rate limited.** Wrap the call in exponential backoff that honors
`X-RateLimit-Reset`. Full retry helper: [references/error-reference.md](references/error-reference.md).

For a full triage sweep (auth + rate limit + Intercom status in one command),
run the script in [references/diagnostics.md](references/diagnostics.md).

## Resources

- [Error Codes](https://developers.intercom.com/docs/references/rest-api/errors/error-codes)
- [HTTP Responses](https://developers.intercom.com/docs/references/rest-api/errors/http-responses)
- [Rate Limiting](https://developers.intercom.com/docs/references/rest-api/errors/rate-limiting)
- [Intercom Status](https://status.intercom.com)
- [Full error reference](references/error-reference.md) — per-code causes and fixes
- [Diagnostics](references/diagnostics.md) — one-shot health-check script

## Next Steps

For deeper, end-to-end debugging of an Intercom integration — capturing request/response pairs, replaying failing calls, and correlating `request_id`s across a session — see the `intercom-debug-bundle` skill in this pack.


---
Source attribution: jeremylongshore
Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/intercom-pack/skills/intercom-common-errors/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2025 Jeremy Longshore

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: jeremylongshore
Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/intercom-pack/skills/intercom-common-errors/SKILL.md
Attribution basis: Source repository record

Fields of work: Sales, Customer Support
Roles: Customer Success Manager, Support Agent, Technical Support
Specialties: API
Tools: Intercom
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 0f0222a77bf817ee42586da23f2b1688ffdfb3241ce5af664ad28641519b70d5