Error Handling - Cakemail

Understand error messages, HTTP status codes, and how to troubleshoot issues with the Cakemail CLI.

Overview

The Cakemail CLI provides user-friendly error messages with:

Clear error descriptions - What went wrong
Helpful suggestions - How to fix the issue
Actionable tips - Next steps to take

Understanding errors helps you debug issues quickly and work more efficiently.

Error Message Format

When an error occurs, you'll see a structured message:

✗ Error: Campaign not found

→ Campaign 12345 doesn't exist or you don't have access

💡 Tip:
  To see all campaigns, use: cakemail campaigns list

Components:

Error message (red) - Brief description of the error
Suggestion (yellow) - Specific context about what went wrong
Tip (gray) - Helpful advice on how to resolve

HTTP Status Codes

The CLI maps API HTTP status codes to user-friendly messages.

400 - Bad Request

What it means: Invalid request parameters

Example:

$ cakemail campaigns create -n "Test"

✗ Error: Invalid request parameters

→ Check the parameters for 'create' operation

💡 Tip:
  Use --help to see available options

Common causes:

Missing required parameters
Invalid parameter values
Malformed data (e.g., invalid JSON)

How to fix:

Check the command syntax: cakemail campaigns create --help
Verify all required options are provided
Validate parameter values (e.g., email format, date format)

401 - Unauthorized

What it means: Authentication failed

Example:

$ cakemail campaigns list

✗ Error: Authentication failed

→ Your credentials are invalid or expired

💡 Tip:
  To re-authenticate, run: cakemail account logout --force
  Then run any command to authenticate again
  Or check your .env file credentials

Common causes:

Invalid access token
Incorrect email/password
Expired session
Missing credentials

How to fix:

Verify credentials in .env file
Test credentials: cakemail account test

Re-authenticate:

cakemail account logout --force
# Then run any command to authenticate again

Generate new access token if using token auth

403 - Forbidden

What it means: Permission denied

Example:

$ cakemail campaigns delete 12345 --force

✗ Error: Permission denied

→ You don't have permission to access this campaign

💡 Tip:
  Check if campaign 12345 exists and you have access

Common causes:

Accessing a resource you don't own
Insufficient account permissions
Wrong account context

How to fix:

Verify you're using the correct account:
```
cakemail account show
```
Check if resource exists:
```
cakemail campaigns get 12345
```

Switch to correct account if needed:

cakemail account use <correct-account-id>

404 - Not Found

What it means: Resource doesn't exist

Example:

$ cakemail campaigns get 99999

✗ Error: Campaign not found

→ Campaign with ID '99999' doesn't exist

💡 Tip:
  To see all campaigns, use: cakemail campaigns list

Common causes:

Wrong resource ID
Resource was deleted
Typo in ID
Wrong account context

How to fix:

List available resources:

cakemail campaigns list
cakemail lists list
cakemail contacts list <list-id>

Verify the ID is correct
Check you're in the right account context

409 - Conflict

What it means: Resource already exists

Example:

$ cakemail senders create -n "John" -e "john@example.com"

✗ Error: Conflict - resource already exists

→ This sender already exists or conflicts with existing data

💡 Tip:
  Try updating the existing resource instead of creating a new one

Common causes:

Duplicate email addresses
Duplicate names (in some resources)
Resource already exists

How to fix:

Check if resource exists:

cakemail senders list --filter "email==john@example.com"

Update existing resource instead:

cakemail senders update <id> -n "John Updated"

422 - Validation Error

What it means: Invalid field values

Example:

$ cakemail contacts add 123 -e "invalid-email"

✗ Error: Validation error

→ email: Invalid email format
  first_name: Field is required

💡 Tip:
  Check the error details above for specific field errors

Common causes:

Invalid email format
Missing required fields
Field value out of range
Invalid date format

How to fix:

Check error details for specific field issues
Validate input formats:
- Email: user@example.com
- Date: YYYY-MM-DD (e.g., 2024-06-15)
- JSON: Valid JSON syntax
Provide all required fields

429 - Rate Limit Exceeded

What it means: Too many requests

Example:

✗ Error: Rate limit exceeded

→ You're making too many requests

💡 Tip:
  Wait a moment before trying again, or reduce request frequency

Common causes:

Running scripts too quickly
Multiple parallel requests
Hitting API rate limits

How to fix:

Add delays between requests in scripts:

for id in $IDS; do
  cakemail campaigns get $id
  sleep 1  # Wait 1 second between requests
done

Reduce parallelism
Batch operations where possible

500 - Server Error

What it means: Internal server error

Example:

✗ Error: Server error

→ Something went wrong on the Cakemail server

💡 Tip:
  This is not your fault. Please try again in a few moments or contact support

Common causes:

Temporary server issue
Unexpected API error
Service degradation

How to fix:

Wait a few minutes and retry
Check Cakemail status page (if available)
Contact support if persists

502/503 - Service Unavailable

What it means: API temporarily unavailable

Example:

✗ Error: Service unavailable

→ The Cakemail API is temporarily down for maintenance

💡 Tip:
  Please try again later

Common causes:

Scheduled maintenance
Service outage
Network issues

How to fix:

Wait and retry later
Check Cakemail announcements
Monitor status updates

Common Error Patterns

Network Connection Errors

Error:

✗ Error: Network connection error

→ Unable to connect to the Cakemail API

💡 Tip:
  Check your internet connection
  Verify the API endpoint is correct
  Check if there's a firewall blocking the connection

Causes:

No internet connection
Firewall blocking requests
VPN issues
Incorrect API base URL

Solutions:

Test internet: ping api.cakemail.dev
Check firewall settings
Verify .env file doesn't override API base URL
Try different network

Invalid Email Address

Error:

✗ Error: Invalid email address

→ Please provide a valid email address

💡 Tip:
  Example: user@example.com

Causes:

Missing @ symbol
Invalid domain
Special characters
Spaces in email

Solutions:

Check email format: user@domain.com
Remove spaces and special characters
Verify domain has proper TLD

Missing Credentials

Error:

✗ Error: Missing credentials

→ Authentication credentials are not configured

💡 Tip:
  Set credentials in .env file or environment variables:
    CAKEMAIL_EMAIL=your@email.com
    CAKEMAIL_PASSWORD=your_password

  Or run any command to authenticate interactively

Causes:

No .env file
Missing environment variables
Typo in credential variable names

Solutions:

Create .env file:

CAKEMAIL_ACCESS_TOKEN=your_token
# OR
CAKEMAIL_EMAIL=your@email.com
CAKEMAIL_PASSWORD=your_password

Set environment variables:

export CAKEMAIL_ACCESS_TOKEN=your_token

Run command to authenticate interactively

Resource Not Found

Error:

✗ Error: List not found

→ List 123 doesn't exist or you don't have access

💡 Tip:
  Use: cakemail lists list    to see all available lists

Causes:

Wrong ID
Resource deleted
Wrong account
Typo

Solutions:

List resources:

cakemail lists list
cakemail campaigns list
cakemail contacts list <list-id>

Verify account context:
```
cakemail account show
```
Check ID for typos

Debugging Strategies

1. Check Command Syntax

Always verify command syntax first:

# Get help for specific command
cakemail campaigns create --help
cakemail contacts add --help

2. Test Authentication

Verify credentials work:

cakemail account test
cakemail account show

3. Verify Resource Exists

Before operating on a resource, check it exists:

# Check campaign exists
cakemail campaigns get 12345

# Check list exists
cakemail lists get 789

# Check contact exists
cakemail contacts get <list-id> <contact-id>

4. Use JSON Format for Details

JSON output provides full error details:

cakemail -f json campaigns create -n "Test"

5. Check Account Context

Verify you're using the correct account:

cakemail account show
cakemail account list

6. Test with Simple Operations

Start with basic operations that should work:

# List operations rarely fail
cakemail campaigns list --limit 1
cakemail lists list --limit 1

7. Validate Input Data

Test input values before using in commands:

# Test email format
echo "user@example.com" | grep -E '^[^\s@]+@[^\s@]+\.[^\s@]+$'

# Test JSON syntax
echo '{"key":"value"}' | jq .

# Test date format
date -d "2024-06-15" || echo "Invalid date"

Validation Helpers

The CLI includes built-in validation for common data types:

Email Validation

Valid:

user@example.com
john.doe@company.co.uk
admin+tag@domain.com

Invalid:

user@ (missing domain)
@example.com (missing user)
user @example.com (space)
user (missing @)

ID Validation

Valid:

123
456789

Invalid:

-1 (negative)
0 (zero)
abc (non-numeric)
12.5 (decimal)

Date Validation

Valid:

2024-06-15
2024-01-01

Invalid:

06/15/2024 (wrong format)
2024-6-15 (missing zero padding)
2024-13-01 (invalid month)
tomorrow (text)

JSON Validation

Valid:

'{"name":"John","age":30}'
'{"key":"value"}'

Invalid:

'{name:John}' (unquoted keys)
"{'name':'John'}" (single quotes)
'{name}' (incomplete)

Error Handling in Scripts

Exit Codes

The CLI returns exit codes for scripting:

0 - Success
1 - Error

Example:

#!/bin/bash

if cakemail campaigns get 12345; then
  echo "Campaign exists"
else
  echo "Campaign not found"
  exit 1
fi

Capturing Errors

Capture stderr:

ERROR=$(cakemail campaigns get 99999 2>&1)
if [ $? -ne 0 ]; then
  echo "Error occurred: $ERROR"
fi

Check JSON response:

RESPONSE=$(cakemail -f json campaigns get 12345 2>&1)
if echo "$RESPONSE" | jq -e . > /dev/null 2>&1; then
  # Valid JSON - success
  echo "Success"
else
  # Error occurred
  echo "Error: $RESPONSE"
fi

Retry Logic

Simple retry:

MAX_RETRIES=3
RETRY=0

while [ $RETRY -lt $MAX_RETRIES ]; do
  if cakemail campaigns get 12345; then
    break
  fi
  RETRY=$((RETRY + 1))
  echo "Retry $RETRY of $MAX_RETRIES..."
  sleep 2
done

Getting Help

When errors persist:

Check documentation
- This user manual
- Command help: cakemail <command> --help
Search existing issues
- GitHub: https://github.com/cakemail-org/cakemail-cli/issues
Create new issue
- Include CLI version: cakemail --version
- Include full error message
- Include command you ran (redact credentials)
- Include OS and Node.js version
Contact support
- For API-related issues
- For account-specific problems

Error Prevention Tips

1. Validate Before Creating

# Bad: Create without checking
cakemail lists create -n "Newsletter"

# Good: Check if exists first
cakemail lists list --filter "name==Newsletter" | grep Newsletter || \
  cakemail lists create -n "Newsletter"

2. Use --help Frequently

# Always check command syntax
cakemail campaigns create --help

3. Test with --limit 1

# Test operations on small datasets
cakemail campaigns list --limit 1

4. Use Confirmation Flags

# CLI prompts for confirmation on destructive operations
cakemail campaigns delete 12345

# Use --force carefully
cakemail campaigns delete 12345 --force

5. Keep Credentials Updated

# Test regularly
cakemail account test