Error Codes

When an API request fails, the response includes an error code and message to help you understand and handle the issue.

Error Response Format

All error responses follow this structure:

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

Error Code Reference

Code	HTTP	Description
`BAD_REQUEST`	400	Invalid request parameters or malformed JSON
`INVALID_EMAIL`	400	Email address format is invalid
`INVALID_JSON`	400	Request body is not valid JSON
`MISSING_REQUIRED`	400	Required parameter is missing
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	API key does not have permission
`NOT_FOUND`	404	Resource not found
`INSUFFICIENT_CREDITS`	402	Not enough credits for this operation
`RATE_LIMITED`	429	Too many requests, slow down
`JOB_NOT_FOUND`	404	Verification job not found
`JOB_NOT_COMPLETE`	400	Job is still processing
`FILE_TOO_LARGE`	400	Uploaded file exceeds 50MB limit
`INVALID_FILE_FORMAT`	400	File must be CSV or TXT
`BATCH_TOO_LARGE`	400	Batch exceeds maximum email limit
`WEBHOOK_FAILED`	400	Webhook URL is unreachable
`INTERNAL_ERROR`	500	Unexpected server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

Handling Errors

4xx Client Errors

These errors indicate a problem with the request. Check the error message, fix the issue, and retry.

429 Rate Limited

Wait for the retry_after seconds before retrying. Implement exponential backoff for repeated failures.

5xx Server Errors

These are server-side issues. Retry with exponential backoff. If the problem persists, contact support.

Example: Error Handling in Node.js

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

    const data = await response.json();

    if (!data.success) {
      switch (data.error.code) {
        case 'RATE_LIMITED':
          // Wait and retry
          const retryAfter = data.error.retry_after || 60;
          await sleep(retryAfter * 1000);
          return verifyEmail(email);

        case 'INSUFFICIENT_CREDITS':
          // Handle billing issue
          throw new Error('Please add credits to continue');

        case 'INVALID_EMAIL':
          // Skip invalid emails
          return { status: 'invalid', reason: 'format' };

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

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

Need Help?

If you're experiencing persistent errors, check our status page for any ongoing issues, or contact support.