Customerio Common Errors

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

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

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.