Error Handling

Error Structure

When an error occurs, the API returns a response with the following structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": {
      // Additional information when available
    }
  }
}

Error Codes

Authentication Errors

UNAUTHORIZED

Status: 401The API key is missing, invalid, or expired.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Solution: Verify that the key is correct and not expired.

FORBIDDEN

Status: 403The key doesn’t have permission for this resource.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this resource"
  }
}

Solution: Check your key permissions in the dashboard.

Validation Errors

VALIDATION_ERROR

Status: 400The submitted data is invalid.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  }
}

Solution: Fix the fields indicated in details.

MISSING_FIELD

Status: 400A required field was not sent.

{
  "error": {
    "code": "MISSING_FIELD",
    "message": "Required field missing",
    "details": {
      "field": "phone"
    }
  }
}

Solution: Include the required field in the request.

Resource Errors

NOT_FOUND

Status: 404The requested resource doesn’t exist.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Lead not found"
  }
}

Solution: Verify that the ID is correct.

ALREADY_EXISTS

Status: 409A resource with the same data already exists.

{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A lead with this phone number already exists"
  }
}

Solution: Use the update endpoint or use different data.

Rate Limit Errors

RATE_LIMIT_EXCEEDED

Status: 429Too many requests in a short time.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": {
      "retry_after": 60
    }
  }
}

Solution: Wait for the time indicated in retry_after (seconds).

Implementing Retry Logic

async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const data = await response.json();
        const retryAfter = data.error?.details?.retry_after || 60;
        console.log(`Rate limited. Retrying in ${retryAfter}s...`);
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }

      if (response.status >= 500) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Server error. Retrying in ${delay}ms...`);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(r => setTimeout(r, delay));
    }
  }
}

import time
import requests

def request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers)

            if response.status_code == 429:
                retry_after = response.json().get('error', {}).get('details', {}).get('retry_after', 60)
                print(f"Rate limited. Retrying in {retry_after}s...")
                time.sleep(retry_after)
                continue

            if response.status_code >= 500:
                delay = (2 ** attempt)
                print(f"Server error. Retrying in {delay}s...")
                time.sleep(delay)
                continue

            return response

        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")

Best Practices

Always Check Status

Never assume the request was successful. Always check the HTTP code.

Implement Retry

For 5xx and 429 errors, implement retry with exponential backoff.

Log Errors

Record errors for debugging and monitoring.

Handle Specific Cases

Implement specific handling for each error type.

Getting Started

Core Concepts

Best Practices

Error Structure

Error Codes

Authentication Errors

Validation Errors

Resource Errors

Rate Limit Errors

Implementing Retry Logic

Best Practices

Always Check Status

Implement Retry

Log Errors

Handle Specific Cases

​Error Structure

​Error Codes

​Authentication Errors

​Validation Errors

​Resource Errors

​Rate Limit Errors

​Implementing Retry Logic

​Best Practices

Always Check Status

Implement Retry

Log Errors

Handle Specific Cases

Error Structure

Error Codes

Authentication Errors

Validation Errors

Resource Errors

Rate Limit Errors

Implementing Retry Logic

Best Practices