Error Handling

How to handle errors from the ClearBounce API.

Error Response Format

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable description"
  }
}

Or for HTTP errors:

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "error": "Unauthorized",
  "message": "Invalid API key"
}

HTTP Status Codes

Code	Name	Description
200	OK	Request successful
400	Bad Request	Invalid request data
401	Unauthorized	Invalid or missing API key
402	Payment Required	Insufficient credits
404	Not Found	Resource not found
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

---

Common Errors

Authentication Errors

UNAUTHORIZED (401)

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Causes:

• Missing X-API-Key header
• Invalid API key
• Deleted API key

Solution:

// Make sure to include the header
const response = await fetch(url, {
  headers: {
    'X-API-Key': 'cb_live_your_api_key' // Don't forget this!
  }
});

---

Credit Errors

INSUFFICIENT_CREDITS (402)

{
  "statusCode": 402,
  "code": "INSUFFICIENT_CREDITS",
  "error": "Payment Required",
  "message": "Insufficient credits"
}

Cause: Your account has no remaining credits.

Solution: Purchase more credits at clearbounce.net/pricing

Prevention:

// Check credits before bulk operations
const response = await fetch('https://api.clearbounce.net/api/v1/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
  },
  body: JSON.stringify({ email: 'test@clearbounce.test' })
});

const result = await response.json();
console.log('Credits remaining:', result.creditsRemaining);

---

Validation Errors

VALIDATION_ERROR (400/422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format"
  }
}

Common causes:

• Invalid email format
• Missing required fields
• Invalid field types

Prevention:

// Validate email format before API call
function isValidEmail(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

if (!isValidEmail(email)) {
  console.log('Invalid email format');
  return;
}

// Now call the API
const result = await verifyEmail(email);

---

Rate Limit Errors

RATE_LIMITED (429)

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}

Cause: Too many requests in a short period.

Solution: Implement retry with backoff:

async function verifyWithRetry(email, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    const response = await fetch('https://api.clearbounce.net/api/v1/verify', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.CLEARBOUNCE_API_KEY
      },
      body: JSON.stringify({ email })
    });

    if (response.status === 429) {
      const waitTime = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
      console.log(`Rate limited. Waiting ${waitTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }

    return response.json();
  }

  throw new Error('Max retries exceeded');
}

---

Resource Not Found

NOT_FOUND (404)

{
  "statusCode": 404,
  "code": "NOT_FOUND",
  "error": "Not Found",
  "message": "Job not found"
}

Causes:

• Invalid job ID
• Job expired (older than 7 days)
• Resource doesn't exist

---

Server Errors

INTERNAL_ERROR (500)

{
  "statusCode": 500,
  "code": "INTERNAL_ERROR",
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Cause: Something went wrong on our end.

Solution:

• Retry the request
• Contact support if the problem persists

---

Error Handling Best Practices

1. Always Check for Errors

async function verifyEmail(email) {
  try {
    const response = await fetch('https://api.clearbounce.net/api/v1/verify', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.CLEARBOUNCE_API_KEY
      },
      body: JSON.stringify({ email })
    });

    const data = await response.json();

    // Check HTTP status
    if (!response.ok) {
      throw new Error(data.message || `HTTP ${response.status}`);
    }

    // Check API success flag
    if (!data.success) {
      throw new Error(data.error?.message || 'Verification failed');
    }

    return data;
  } catch (error) {
    console.error('Verification error:', error.message);
    throw error;
  }
}

2. Handle Specific Error Types

async function handleVerification(email) {
  try {
    return await verifyEmail(email);
  } catch (error) {
    switch (error.code) {
      case 'UNAUTHORIZED':
        console.error('Check your API key');
        break;
      case 'INSUFFICIENT_CREDITS':
        console.error('Purchase more credits');
        break;
      case 'RATE_LIMITED':
        console.error('Slow down requests');
        break;
      case 'VALIDATION_ERROR':
        console.error('Check email format');
        break;
      default:
        console.error('Unknown error:', error.message);
    }
    throw error;
  }
}

3. Log Errors for Debugging

async function verifyWithLogging(email) {
  const startTime = Date.now();

  try {
    const result = await verifyEmail(email);
    console.log({
      email,
      status: result.data.status,
      duration: Date.now() - startTime
    });
    return result;
  } catch (error) {
    console.error({
      email,
      error: error.message,
      code: error.code,
      duration: Date.now() - startTime
    });
    throw error;
  }
}

---

Need Help?

If you encounter persistent errors:

1. Check our status page for outages
2. Review the error message and code
3. Contact support: support@clearbounce.net