customerio-common-errors
Diagnose and fix Customer.io common errors. Use when troubleshooting API errors, delivery issues, or integration problems with Customer.io. Trigger with phrases like "customer.io error", "customer.io not working", "debug customer.io", "customer.io issue".
Installation
Details
Usage
After installing, this skill will be available to your AI coding assistant.
Verify installation:
skills listSkill Instructions
name: customerio-common-errors description: | Diagnose and fix Customer.io common errors. Use when troubleshooting API errors, delivery issues, or integration problems with Customer.io. Trigger with phrases like "customer.io error", "customer.io not working", "debug customer.io", "customer.io issue". allowed-tools: Read, Grep, Bash(curl:*) version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io
Customer.io Common Errors
Overview
Diagnose and resolve common Customer.io integration errors, delivery issues, and API problems.
Error Categories
Authentication Errors
Error: 401 Unauthorized
{
"meta": {
"error": "Unauthorized"
}
}
Cause: Invalid Site ID or API Key Solution:
- Verify credentials in Customer.io Settings > API Credentials
- Check you're using Track API key (not App API key) for identify/track
- Ensure environment variables are loaded correctly
# Verify environment variables
echo "Site ID: ${CUSTOMERIO_SITE_ID:0:8}..."
echo "API Key: ${CUSTOMERIO_API_KEY:0:8}..."
Error: 403 Forbidden
Cause: API key doesn't have required permissions Solution: Generate new API key with correct scope (Track vs App API)
Request Errors
Error: 400 Bad Request - Invalid identifier
{
"meta": {
"error": "identifier is required"
}
}
Cause: Missing or empty user ID Solution:
// Wrong
await client.identify('', { email: 'user@example.com' });
// Correct
await client.identify('user-123', { email: 'user@example.com' });
Error: 400 Bad Request - Invalid timestamp
{
"meta": {
"error": "timestamp must be a valid unix timestamp"
}
}
Cause: Using milliseconds instead of seconds Solution:
// Wrong
{ created_at: Date.now() } // 1704067200000
// Correct
{ created_at: Math.floor(Date.now() / 1000) } // 1704067200
Error: 400 Bad Request - Invalid email
Cause: Malformed email address Solution:
// Validate email before sending
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(email)) {
throw new Error('Invalid email format');
}
Rate Limiting
Error: 429 Too Many Requests
{
"meta": {
"error": "Rate limit exceeded"
}
}
Cause: Exceeded API rate limits Solution:
// Implement exponential backoff
async function withBackoff(fn: () => Promise<any>, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
try {
return await fn();
} catch (error: any) {
if (error.status === 429 && i < maxRetries - 1) {
const delay = Math.pow(2, i) * 1000;
await new Promise(r => setTimeout(r, delay));
continue;
}
throw error;
}
}
}
Delivery Issues
Issue: Email not delivered
Diagnostic steps:
- Check People > User > Activity for event receipt
- Verify campaign is active and user matches segment
- Check Deliverability > Suppression list
- Review message preview for errors
# Check user exists via API
curl -X GET "https://track.customer.io/api/v1/customers/user-123" \
-u "$CUSTOMERIO_SITE_ID:$CUSTOMERIO_API_KEY"
Issue: Event not triggering campaign
Cause: Event name mismatch or missing attributes Solution:
// Check exact event name in dashboard
// Event names are case-sensitive
await client.track(userId, {
name: 'signed_up', // Must match exactly
data: { source: 'web' }
});
Issue: User not in segment
Cause: Missing or incorrect attributes Solution:
- Check segment conditions in dashboard
- Verify user has required attributes
- Check attribute types match (string vs number)
SDK-Specific Errors
Node.js: TypeError - Cannot read property
// Wrong - SDK not initialized
const client = new TrackClient(undefined, undefined);
// Correct - Check env vars exist
if (!process.env.CUSTOMERIO_SITE_ID) {
throw new Error('CUSTOMERIO_SITE_ID not set');
}
Python: ConnectionError
# Handle network errors
import customerio
from customerio.errors import CustomerIOError
try:
cio.identify(id='user-123', email='user@example.com')
except CustomerIOError as e:
print(f"Customer.io error: {e}")
except ConnectionError as e:
print(f"Network error: {e}")
Diagnostic Commands
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"
Verify Event Delivery
curl -X POST "https://track.customer.io/api/v1/customers/test-user/events" \
-u "$CUSTOMERIO_SITE_ID:$CUSTOMERIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"test_event","data":{"test":true}}'
Error Handling
| 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 |
Resources
Next Steps
After resolving errors, proceed to customerio-debug-bundle to create comprehensive debug reports.
More by jeremylongshore
View allRabbitmq Queue Setup - Auto-activating skill for Backend Development. Triggers on: rabbitmq queue setup, rabbitmq queue setup Part of the Backend Development skill category.
evaluating-machine-learning-models: This skill allows Claude to evaluate machine learning models using a comprehensive suite of metrics. It should be used when the user requests model performance analysis, validation, or testing. Claude can use this skill to assess model accuracy, precision, recall, F1-score, and other relevant metrics. Trigger this skill when the user mentions "evaluate model", "model performance", "testing metrics", "validation results", or requests a comprehensive "model evaluation".
building-neural-networks: This skill allows Claude to construct and configure neural network architectures using the neural-network-builder plugin. It should be used when the user requests the creation of a new neural network, modification of an existing one, or assistance with defining the layers, parameters, and training process. The skill is triggered by requests involving terms like "build a neural network," "define network architecture," "configure layers," or specific mentions of neural network types (e.g., "CNN," "RNN," "transformer").
Oauth Callback Handler - Auto-activating skill for API Integration. Triggers on: oauth callback handler, oauth callback handler Part of the API Integration skill category.