Error Handling

Understanding API errors and how to handle them.

Error Response Format

All errors return a consistent JSON format:

{
  "error": "Error message here",
  "code": "ERROR_CODE",
  "details": { ... }  // Optional additional information
}

HTTP Status Codes

2xx Success

200 - Request succeeded
201 - Resource created
204 - Request succeeded, no content returned

4xx Client Errors

400 - Bad request (invalid parameters)
401 - Unauthorized (missing/invalid API key)
403 - Forbidden (insufficient permissions)
404 - Resource not found
409 - Conflict (idempotency key reused)
422 - Validation error
429 - Rate limit exceeded

5xx Server Errors

500 - Internal server error
502 - Bad gateway
503 - Service temporarily unavailable

Common Errors

Invalid From Address

{
  "error": "Domain not verified",
  "code": "DOMAIN_NOT_VERIFIED"
}

The domain in the "from" address isn't verified or not linked to your API key.

Missing Required Field

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "to": "Required field"
  }
}

One or more required fields are missing from your request.

Invalid Email Address

{
  "error": "Invalid email address",
  "code": "INVALID_EMAIL",
  "details": {
    "field": "to",
    "value": "not-an-email"
  }
}

One of the email addresses in the request is invalid.

Email Limit Exceeded

{
  "error": "Monthly email limit exceeded",
  "code": "LIMIT_EXCEEDED",
  "details": {
    "limit": 10000,
    "used": 10000
  }
}

You've reached your plan's monthly email limit.

Handling Errors

async function sendEmail(email) {
  const response = await fetch('https://getmailer.co/api/emails', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(email)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 400:
      case 422:
        // Validation error - fix the request
        console.error('Invalid request:', error.details);
        throw new Error(error.error);

      case 401:
        // Auth error - check API key
        throw new Error('Invalid API key');

      case 429:
        // Rate limited - retry after delay
        const retryAfter = error.retryAfter || 60;
        await sleep(retryAfter * 1000);
        return sendEmail(email); // Retry

      case 500:
      case 502:
      case 503:
        // Server error - retry with backoff
        await sleep(5000);
        return sendEmail(email);

      default:
        throw new Error(error.error);
    }
  }

  return response.json();
}