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

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.

customerio-common-errors