Error Handling

Understanding and handling errors returned by the Sendmator API.

Error Response Format

All errors follow a consistent structure:

{
  "error": {
    "type": "error_type",
    "message": "Human-readable error message",
    "details": {
      "field": "field_name",
      "code": "error_code"
    }
  }
}

Error Types

Validation Errors (validation_error)

Invalid request parameters:

{
  "error": {
    "type": "validation_error",
    "message": "Invalid email address",
    "details": {
      "field": "to",
      "code": "invalid_email"
    }
  }
}

Authentication Errors (authentication_error)

Invalid or missing API key:

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided"
  }
}

Rate Limit Errors (rate_limit_error)

Too many requests:

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

Server Errors (server_error)

Internal server issues:

{
  "error": {
    "type": "server_error",
    "message": "An internal server error occurred"
  }
}

HTTP Status Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
502	Bad Gateway
503	Service Unavailable

Error Handling Best Practices

1. Always Handle Errors

try {
  const result = await sendmator.emails.send(emailData);
  console.log('Success:', result.id);
} catch (error) {
  console.error('Error:', error.message);
  // Handle the error appropriately
}

2. Check Error Types

try {
  await sendmator.emails.send(emailData);
} catch (error) {
  switch (error.type) {
    case 'validation_error':
      console.error('Validation failed:', error.details);
      break;
    case 'rate_limit_error':
      console.error('Rate limit exceeded, retrying...');
      // Implement retry logic
      break;
    case 'authentication_error':
      console.error('Invalid API key');
      break;
    default:
      console.error('Unexpected error:', error.message);
  }
}

3. Implement Retry Logic

async function sendEmailWithRetry(emailData, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await sendmator.emails.send(emailData);
    } catch (error) {
      if (shouldRetry(error) && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

function shouldRetry(error) {
  return error.status >= 500 || error.status === 429;
}

4. Log Errors for Debugging

const logger = require('winston');

try {
  await sendmator.emails.send(emailData);
} catch (error) {
  logger.error('Email send failed', {
    error: error.message,
    type: error.type,
    status: error.status,
    requestId: error.requestId,
    emailData: emailData
  });
  
  // Don't expose internal errors to users
  throw new Error('Failed to send email. Please try again.');
}

Common Error Scenarios

Invalid Email Address

{
  "error": {
    "type": "validation_error",
    "message": "Invalid email address",
    "details": {
      "field": "to",
      "code": "invalid_email"
    }
  }
}

Solution: Validate email addresses before sending.

Missing Required Fields

{
  "error": {
    "type": "validation_error",
    "message": "Missing required field: subject",
    "details": {
      "field": "subject",
      "code": "required"
    }
  }
}

Solution: Ensure all required fields are included.

Template Not Found

{
  "error": {
    "type": "not_found_error",
    "message": "Template 'welcome-email' not found"
  }
}

Solution: Verify template ID exists before using.

Attachment Too Large

{
  "error": {
    "type": "validation_error",
    "message": "Attachment exceeds maximum size limit",
    "details": {
      "field": "attachments",
      "code": "file_too_large"
    }
  }
}

Solution: Reduce attachment size or use cloud storage links.

Testing Error Scenarios

Use these test email addresses to simulate errors:

• invalid@sendmator-test.com - Triggers validation error
• bounce@sendmator-test.com - Triggers bounce
• reject@sendmator-test.com - Triggers rejection

// Test error handling
try {
  await sendmator.emails.send({
    to: 'invalid@sendmator-test.com',
    from: 'test@yourapp.com',
    subject: 'Test',
    html: '<p>Test</p>'
  });
} catch (error) {
  console.log('Expected error:', error.type);
}