Common Errors

Common error codes and their solutions when using Keplers Mail Service.

Authentication Errors

401 Unauthorized

Message: Invalid API key

Solutions:

• Check Authorization header format: Bearer YOUR_API_KEY
• Verify API key is active in dashboard
• Ensure API key belongs to correct workspace

403 Forbidden

Message: Insufficient permissions

Solutions:

• Check API key permissions in dashboard
• Generate new API key with required permissions
• Verify workspace access

Request Format Errors

400 Bad Request - Invalid Email

Message: Invalid email address format

Solution:

// Validate emails before sending
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
const isValid = emailRegex.test(email);

400 Bad Request - Missing Fields

Message: Missing required field

Required fields:

• to - array of email addresses
• subject - email subject line
• body OR template_id - email content

422 Template Error

Message: Template parameter missing

Solution:

{
  "template_id": "welcome",
  "params": {
    "user_name": "John",
    "company": "Acme Corp"
  }
}

Rate Limiting

429 Too Many Requests

Message: Rate limit exceeded

Solution:

// Wait for rate limit reset
if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
}

Provider Errors

401 OAuth Token Expired

Message: OAuth token expired

Solution:

• Go to Connected Emails in dashboard
• Click "Reconnect" on expired account
• Complete OAuth authorization

503 Provider Unavailable

Message: Email provider temporarily unavailable

Solutions:

• Check provider status pages
• Implement retry logic
• Use different connected email if available

Getting Help

Support: [email protected]

Still having issues? Check the Getting Started guide.