Customer.io Common Errors

// WRONG — mixing up API key types
import { TrackClient, APIClient, RegionUS } from "customerio-node";

// Track API uses Site ID + Track API Key (Basic Auth)
const cio = new TrackClient(siteId, trackApiKey, { region: RegionUS });

// App API uses App API Key (Bearer Auth) — DIFFERENT key
const api = new APIClient(appApiKey, { region: RegionUS });

// Common mistake: using Track API key for App API client
// const api = new APIClient(trackApiKey); // WRONG — will get 401

// WRONG — Customer.io expects Unix seconds, not milliseconds
await cio.identify("user-1", {
  created_at: Date.now(),              // 1704067200000 — TOO LARGE
});

// CORRECT — divide by 1000
await cio.identify("user-1", {
  created_at: Math.floor(Date.now() / 1000),  // 1704067200
});

// WRONG — event name doesn't match dashboard
await cio.track("user-1", { name: "SignedUp", data: {} });
// Dashboard expects: "signed_up" (case-sensitive)

// CORRECT — exact match, snake_case
await cio.track("user-1", { name: "signed_up", data: {} });

import { APIClient, SendEmailRequest, RegionUS } from "customerio-node";

const api = new APIClient(process.env.CUSTOMERIO_APP_API_KEY!, {
  region: RegionUS,
});

// Common 422 errors:
// 1. Wrong transactional_message_id
const request = new SendEmailRequest({
  to: "user@example.com",
  transactional_message_id: "999",     // Must exist in dashboard
  message_data: { name: "Jane" },
  identifiers: { id: "user-123" },
});

// 2. Missing required message_data fields
// If template uses {{ data.reset_url }}, message_data must include reset_url

// 3. Invalid email address
// "to" must be a valid email format

// Implement backoff when you hit 429
async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err.statusCode === 429 && i < maxRetries) {
        // Respect Retry-After header if present, otherwise exponential backoff
        const retryAfter = err.headers?.["retry-after"];
        const delay = retryAfter
          ? parseInt(retryAfter) * 1000
          : Math.pow(2, i) * 1000 + Math.random() * 500;
        console.warn(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
      throw err;
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage
await withBackoff(() => cio.identify("user-1", { email: "user@example.com" }));

// WRONG — EU account hitting US endpoint
const cio = new TrackClient(siteId, apiKey, { region: RegionUS });
// Returns 401 because credentials are for EU workspace

// CORRECT
import { RegionEU } from "customerio-node";
const cio = new TrackClient(siteId, apiKey, { region: RegionEU });

# Test Track API authentication
curl -s -w "\nHTTP %{http_code}\n" \
  -u "$CUSTOMERIO_SITE_ID:$CUSTOMERIO_TRACK_API_KEY" \
  -X PUT "https://track.customer.io/api/v1/customers/test-diag" \
  -H "Content-Type: application/json" \
  -d '{"email":"diag@example.com"}'

# Test App API authentication
curl -s -w "\nHTTP %{http_code}\n" \
  -H "Authorization: Bearer $CUSTOMERIO_APP_API_KEY" \
  "https://api.customer.io/v1/campaigns"

# Check Customer.io status
curl -s "https://status.customer.io/api/v2/status.json" | python3 -m json.tool

// Centralized error handler for Customer.io operations
async function safeCioCall<T>(
  operation: string,
  fn: () => Promise<T>
): Promise<T | null> {
  try {
    return await fn();
  } catch (err: any) {
    const code = err.statusCode ?? err.status ?? "unknown";
    console.error(`CIO ${operation} failed [${code}]:`, err.message);

    // Alert on auth errors — likely misconfiguration
    if (code === 401 || code === 403) {
      console.error("AUTH ERROR: Check API credentials immediately");
    }

    // Don't crash the app for tracking failures
    return null;
  }
}

// Usage — never crashes your app
await safeCioCall("identify", () =>
  cio.identify("user-1", { email: "user@example.com" })
);