customerio-common-errors

# 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
```json
{
  "meta": {
    "error": "Unauthorized"
  }
}
```
**Cause**: Invalid Site ID or API Key
**Solution**:
1. Verify credentials in Customer.io Settings > API Credentials
2. Check you're using Track API key (not App API key) for identify/track
3. Ensure environment variables are loaded correctly
```bash
# 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
```json
{
  "meta": {
    "error": "identifier is required"
  }
}
```
**Cause**: Missing or empty user ID
**Solution**:
```typescript
// Wrong
await client.identify('', { email: 'user@example.com' });

// Correct
await client.identify('user-123', { email: 'user@example.com' });
```

#### Error: 400 Bad Request - Invalid timestamp
```json
{
  "meta": {
    "error": "timestamp must be a valid unix timestamp"
  }
}
```
**Cause**: Using milliseconds instead of seconds
**Solution**:
```typescript
// 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**:
```typescript
// 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
```json
{
  "meta": {
    "error": "Rate limit exceeded"
  }
}
```
**Cause**: Exceeded API rate limits
**Solution**:
```typescript
// Implement exponential backoff
async function