菜单
Diagnose and fix Customer.io common errors. Use when troubleshooting API errors, delivery failures, campaign issues, or SDK exceptions. Trigger: "customer.io error", "customer.io not working", "debug customer.io", "customer.io 401", "customer.io 429".
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace --skill customerio-common-errors命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | customerio-common-errors |
| description | Diagnose and fix Customer.io common errors. Use when troubleshooting API errors, delivery failures, campaign issues, or SDK exceptions. Trigger: "customer.io error", "customer.io not working", "debug customer.io", "customer.io 401", "customer.io 429". |
| allowed-tools | Read, Grep, Bash(curl:*), Bash(npx:*) |
| version | 1.14.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","customer-io","debugging","errors"] |
| compatibility | Designed for Claude Code |
Diagnose and fix the most frequent Customer.io integration errors: API status codes, SDK exceptions, delivery failures, campaign trigger issues, and transactional message problems.
| Code | Meaning | Retryable | Action |
|---|---|---|---|
200 | Success | N/A | No action needed |
400 | Bad Request | No | Fix request payload — see details below |
401 | Unauthorized | No | Check API credentials |
403 | Forbidden | No | API key lacks permission for this endpoint |
404 | Not Found | No | Check endpoint URL or resource ID |
408 | Request Timeout | Yes | Retry with backoff |
422 | Unprocessable Entity | No | Validation error — check required fields |
429 | Rate Limited | Yes | Back off, respect Retry-After header |
500 | Internal Server Error | Yes | Retry with exponential backoff |
503 | Service Unavailable | Yes | Check status.customer.io, retry later |
// WRONG — mixing up API key types
import { TrackClient, APIClient, RegionUS } from "customerio-node";
cio = (siteId, trackApiKey, { : });
api = (appApiKey, { : });
Fix: Verify you're using the right key type. Track API credentials are under "Tracking API Key" in Settings. App API key is under "App API Key" — it's a separate bearer token.
// 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
});
Customer.io silently accepts millisecond timestamps but interprets them as dates thousands of years in the future, breaking segment conditions and campaign triggers.
// 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: {} });
Checklist:
identify() first)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 });
Diagnostic checklist:
email attribute? (Check People > user profile)# 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" })
);
After resolving errors, proceed to customerio-debug-bundle for comprehensive debug reports.
