Error Handling

Understanding API error responses.

Error Format

When a request fails, the API returns a consistent JSON error object. The type field identifies the category, message provides a human-readable explanation, and the optional param field indicates which parameter caused the issue.

{
  "error": {
    "type": "invalid_request",
    "message": "The 'email' field is required.",
    "param": "email"
  }
}

Error Types

Type	Status	Description
`invalid_request`	400	The request was malformed or missing required parameters. Check the error message for details on which field failed validation.
`auth_error`	401	No valid API key was provided. Ensure your Authorization header includes a valid Bearer token.
`forbidden`	403	The API key doesn't have permission to perform the requested action. Check your key's scopes.
`not_found`	404	The requested resource doesn't exist. Verify the ID or path is correct.
`rate_limit`	429	Too many requests. Back off and retry after the time indicated in the Retry-After header.
`server_error`	500	Something went wrong on our end. These are rare — if persistent, contact support.

Handling Errors

Always check the HTTP status code and parse the error body. Here’s a recommended pattern for handling errors in your integration:

const response = await fetch('https://app.clawdmail.ai/api/v1/campaigns', {
  headers: { 'Authorization': 'Bearer cm_live_your_key' },
});

if (!response.ok) {
  const { error } = await response.json();
  switch (error.type) {
    case 'auth_error':
      throw new Error('Invalid API key');
    case 'rate_limit':
      const retryAfter = response.headers.get('Retry-After');
      await sleep(Number(retryAfter) * 1000);
      break;
    default:
      throw new Error(error.message);
  }
}

const { data } = await response.json();