Customer.io Common Errors

Overview

Diagnose and resolve common Customer.io integration errors, delivery issues, and API problems.

Prerequisites

• Access to Customer.io dashboard

• API credentials configured

• Access to application logs

Error Reference

Error Code Meaning Action

400 Bad Request Check request format and data

401 Unauthorized Verify API credentials

403 Forbidden Check API key permissions

404 Not Found Verify endpoint URL

429 Rate Limited Implement backoff

500 Server Error Retry with backoff

Instructions

Step 1: Identify the Error Category

Check error response code and message. Authentication errors (401/403) need credential review. Request errors (400) need payload fixes. Rate limits (429) need backoff logic.

Step 2: Fix Authentication Issues

Verify correct API key type (Track vs App). Check environment variables are loaded. Ensure credentials match the workspace.

Step 3: Fix Request Errors

Check for empty user IDs, millisecond timestamps (use Unix seconds), and malformed email addresses. Validate payloads before sending.

Step 4: Handle Rate Limiting

Implement exponential backoff with jitter. Start at 1s delay and double on each retry. Skip retries on 4xx errors (except 429).

Step 5: Debug Delivery Issues

Check user activity in dashboard, verify campaign is active and user matches segment, review suppression list, and check message preview.

Step 6: Fix SDK-Specific Errors

For Node.js, check env vars exist before creating client. For Python, catch both CustomerIOError and ConnectionError .

For detailed code examples and diagnostic commands, load the reference guide: Read(${CLAUDE_SKILL_DIR}/references/implementation-guide.md)

Diagnostic Commands

set -euo pipefail

Check API connectivity

curl -X POST "https://track.customer.io/api/v1/customers/test-user"
-u "$CUSTOMERIO_SITE_ID:$CUSTOMERIO_API_KEY"
-H "Content-Type: application/json"
-d '{"email":"test@example.com"}'
-w "\nHTTP Status: %{http_code}\n"

Error Handling

Issue Solution

Events not triggering campaigns Check exact event name (case-sensitive)

User not in segment Verify required attributes and types

SDK initialization error Check env vars exist before creating client

Resources

• API Error Reference

• Troubleshooting Guide

• Status Page

Next Steps

After resolving errors, proceed to customerio-debug-bundle for comprehensive debug reports.

Output

• Configuration files or code changes applied to the project

• Validation report confirming correct implementation

• Summary of changes made and their rationale

See debugging implementation details for output format specifications.

Examples

Basic usage: Apply customerio common errors to a standard project setup with default configuration options.

Advanced scenario: Customize customerio common errors for production environments with multiple constraints and team-specific requirements.