intercom-common-errors

Intercom Common Errors

Overview

Quick reference for Intercom API errors by HTTP status code, with real error response shapes and proven solutions.

Intercom Error Response Shape

All Intercom errors return this structure:

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

Error Reference

401 Unauthorized

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

Causes:

• Access token is expired, revoked, or malformed
• Using a test token against production (or vice versa)
• Token was regenerated in Developer Hub but not updated in app

Fix:

# Verify token works
curl -s https://api.intercom.io/me \
  -H "Authorization: Bearer $INTERCOM_ACCESS_TOKEN" \
  -H "Accept: application/json" | jq '.type'
# Should return "admin"

# If invalid, regenerate at:
# app.intercom.com > Settings > Developer Hub > Your App > Authentication

---

403 Forbidden

{
  "type": "error.list",
  "errors": [{ "code": "forbidden", "message": "You do not have permission to access this resource" }]
}

Causes:

• OAuth app missing required scope
• Trying to access a resource in another workspace
• Admin permissions insufficient

Fix: Add the required OAuth scope in Developer Hub > OAuth Scopes.

---

404 Not Found

{
  "type": "error.list",
  "errors": [{ "code": "not_found", "message": "User Not Found" }]
}

Causes:

• Contact, conversation, or article ID is invalid
• Resource was deleted
• Using user_id where contact_id is expected (or vice versa)

Fix:

// Always check existence before operating
try {
  const contact = await client.contacts.find({ contactId: id });
} catch (err) {
  if (err instanceof IntercomError && err.statusCode === 404) {
    console.log(`Contact ${id} not found, skipping`);
  }
}

---

409 Conflict

{
  "type": "error.list",
  "errors": [{ "code": "conflict", "message": "A contact matching those details already exists with id=abc123" }]
}

Causes:

• Creating a contact with a duplicate external_id or email
• Race condition in concurrent contact creation

Fix:

// Search first, create if not found
async function findOrCreateContact(email: string, externalId: string) {
  const existing = await client.contacts.search({
    query: { field: "email", operator: "=", value: email },
  });

  if (existing.data.length > 0) {
    return existing.data[0];
  }

  return client.contacts.create({
    role: "user",
    email,
    externalId,
  });
}

---

422 Unprocessable Entity

{
  "type": "error.list",
  "errors": [{ "code": "parameter_invalid", "message": "email is not a valid email address" }]
}

Causes:

• Invalid field value (bad email format, wrong type)
• Missing required field
• Custom attribute name exceeds 190 characters

Fix: Validate inputs before sending. Check the errors array for specifics.

---

429 Rate Limit Exceeded

{
  "type": "error.list",
  "errors": [{ "code": "rate_limit_exceeded", "message": "Rate limit exceeded" }]
}

Response headers:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711100060

Limits: 10,000 req/min per app, 25,000 req/min per workspace.

Fix:

import { IntercomError } from "intercom-client";

async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err instanceof IntercomError && err.statusCode === 429) {
        if (attempt === maxRetries) throw err;
        const resetAt = err.headers?.["x-ratelimit-reset"];
        const waitMs = resetAt
          ? (parseInt(resetAt) * 1000) - Date.now() + 1000
          : 1000 * Math.pow(2, attempt);
        console.log(`Rate limited, waiting ${waitMs}ms`);
        await new Promise(r => setTimeout(r, Math.max(waitMs, 1000)));
      } else {
        throw err;
      }
    }
  }
  throw new Error("Unreachable");
}

---

500/502/503 Server Errors

Causes: Intercom-side issue, not your fault.

Fix:

# 1. Check Intercom status
curl -s https://status.intercom.com/api/v2/summary.json | jq '.status'

# 2. Retry with backoff (same pattern as 429)
# 3. If persistent, contact Intercom support with request_id

Quick Diagnostic Script

#!/bin/bash
TOKEN="${INTERCOM_ACCESS_TOKEN}"

echo "=== Intercom API Diagnostics ==="

# Test auth
echo -n "Auth: "
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  https://api.intercom.io/me)
echo "$STATUS $([ "$STATUS" = "200" ] && echo "OK" || echo "FAIL")"

# Check rate limits
echo -n "Rate limit remaining: "
curl -s -D - -o /dev/null \
  -H "Authorization: Bearer $TOKEN" \
  https://api.intercom.io/me 2>/dev/null | grep -i x-ratelimit-remaining

# Intercom status
echo -n "Intercom status: "
curl -s https://status.intercom.com/api/v2/status.json | jq -r '.status.description'

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

Resources

• Error Codes
• HTTP Responses
• Rate Limiting
• Intercom Status

Next Steps

For comprehensive debugging, see intercom-debug-bundle.