Errors

The Bizzy API uses conventional HTTP status codes and returns detailed error information in JSON format to help you handle errors gracefully.

Error Response Format

All error responses follow a consistent structure:

{
    "error": {
        "code": "ERROR_CODE",
        "message": "A human-readable description of the error",
        "details": {
            // Additional context (optional)
        }
    }
}

Field	Type	Description
`code`	string	A machine-readable error code for programmatic handling
`message`	string	A human-readable description of what went wrong
`details`	object	Additional context about the error (optional)

HTTP Status Codes

Status	Meaning	When It Occurs
`200`	OK	Request succeeded
`201`	Created	Resource was created successfully
`204`	No Content	Request succeeded with no response body (e.g., DELETE)
`400`	Bad Request	Invalid request format or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Valid API key but insufficient permissions
`404`	Not Found	Resource doesn’t exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Something went wrong on our end
`503`	Service Unavailable	Temporary service outage

Error Codes Reference

Authentication Errors

Code	Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`INSUFFICIENT_PERMISSIONS`	403	API key lacks required permissions

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

Validation Errors

Code	Status	Description
`VALIDATION_ERROR`	400	Request body failed validation
`INVALID_INPUT`	400	Invalid query parameters or input
`MISSING_QUERY`	400	Required query parameter is missing

Validation errors include details about which fields failed. details is a tree mirroring the request body: each node has an errors array (issues at that path), and object nodes additionally have a properties map keyed by field name. The top-level errors array carries issues that apply to the request as a whole.

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid request body",
        "details": {
            "errors": [],
            "properties": {
                "email": {
                    "errors": ["Invalid email address"]
                },
                "name": {
                    "errors": [
                        "Too small: expected string to have >=1 characters"
                    ]
                }
            }
        }
    }
}

Resource Errors

Code	Status	Description
`NOT_FOUND`	404	Requested resource doesn’t exist
`INVALID_MESSAGE_ID`	400	Invalid message ID format
`INVALID_CONTACT_ID`	400	Invalid contact ID format
`INVALID_BUSINESS_ID`	400	Invalid business ID format

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

For standard resources, GET, PUT/PATCH, and DELETE requests that target a resource which doesn’t exist (or isn’t visible to your organization) all return 404 with the NOT_FOUND code. Updating or deleting a missing resource is never a 500.DNS record write operations (PUT/DELETE /v1/domains/{id}/dns-records/{recordId}) are the exception: they proxy Cloudflare, so a missing record surfaces the upstream status (typically 404) with the DNS_ERROR code rather than NOT_FOUND.

Domain Management Errors

Code	Status	Description
`REGISTRAR_UNSUPPORTED_OPERATION`	422	The requested operation isn’t available for this domain

{
    "error": {
        "code": "REGISTRAR_UNSUPPORTED_OPERATION",
        "message": "WHOIS privacy is always enabled for this domain and cannot be disabled",
        "details": {
            "operation": "disabling WHOIS privacy"
        }
    }
}

A small number of management operations aren’t available for every domain — for example, some domains have WHOIS privacy permanently enabled, so it can’t be disabled. When that happens the request returns 422 with this code and the affected operation.

Rate Limiting Errors

Code	Status	Description
`RATE_LIMITED`	429	Too many requests

{
    "error": {
        "code": "RATE_LIMITED",
        "message": "Rate limit exceeded. Retry after the number of seconds indicated by the Retry-After header."
    }
}

A 429 from your plan’s rate limit carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers — wait Retry-After seconds before retrying (fall back to exponential backoff if the header is absent). See Rate Limits for per-plan limits.

Server Errors

Code	Status	Description
`INTERNAL_ERROR`	500	Unexpected server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

{
    "error": {
        "code": "INTERNAL_ERROR",
        "message": "An unexpected error occurred"
    }
}

Handling Errors

Basic Error Handling

async function makeRequest() {
    const response = await fetch('https://api.bizzyco.ai/v1/contacts', {
        headers: {
            'Authorization': `Bearer ${apiKey}`,
        },
    });

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

        switch (response.status) {
            case 401:
                throw new Error('Invalid API key');
            case 403:
                throw new Error(`Permission denied: ${error.message}`);
            case 404:
                throw new Error('Resource not found');
            case 429:
                throw new Error('Rate limited - retry later');
            default:
                throw new Error(error.message || 'Request failed');
        }
    }

    return response.json();

}

import requests

def make_request():
    response = requests.get(
        'https://api.bizzyco.ai/v1/contacts',
        headers={'Authorization': f'Bearer {api_key}'}
    )

    if not response.ok:
        error = response.json().get('error', {})

        if response.status_code == 401:
            raise Exception('Invalid API key')
        elif response.status_code == 403:
            raise Exception(f"Permission denied: {error.get('message')}")
        elif response.status_code == 404:
            raise Exception('Resource not found')
        elif response.status_code == 429:
            raise Exception('Rate limited - retry later')
        else:
            raise Exception(error.get('message', 'Request failed'))

    return response.json()

Retry with Exponential Backoff

For transient errors (429, 500, 503), implement retry logic with exponential backoff:

async function fetchWithRetry(
    url: string,
    options: RequestInit,
    maxRetries = 3
): Promise<Response> {
    let lastError: Error;

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

            // Don't retry client errors (except rate limiting)
            if (response.ok || (response.status >= 400 && response.status < 500 && response.status !== 429)) {
                return response;
            }

            // For rate limiting, use Retry-After header if available
            if (response.status === 429) {
                const retryAfter = response.headers.get('Retry-After');
                const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
                await new Promise(resolve => setTimeout(resolve, delay));
                continue;
            }

            // For server errors, use exponential backoff
            if (response.status >= 500) {
                const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
                await new Promise(resolve => setTimeout(resolve, delay));
                continue;
            }

            return response;
        } catch (error) {
            lastError = error as Error;
            const delay = Math.pow(2, attempt) * 1000;
            await new Promise(resolve => setTimeout(resolve, delay));
        }
    }

    throw lastError!;

}

import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    last_error = None

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

            # Don't retry client errors (except rate limiting)
            if response.ok or (400 <= response.status_code < 500 and response.status_code != 429):
                return response

            # For rate limiting, use Retry-After header if available
            if response.status_code == 429:
                retry_after = response.headers.get('Retry-After')
                delay = int(retry_after) if retry_after else (2 ** attempt)
                time.sleep(delay)
                continue

            # For server errors, use exponential backoff
            if response.status_code >= 500:
                delay = 2 ** attempt  # 1s, 2s, 4s
                time.sleep(delay)
                continue

            return response
        except requests.RequestException as e:
            last_error = e
            delay = 2 ** attempt
            time.sleep(delay)

    raise last_error

Best Practices

Always check the error code

Use the code field for programmatic error handling, not the message. Error messages may change, but error codes remain stable.

Log errors with context

Include the request ID from response headers (X-Request-ID) when logging errors to help with debugging and support requests.

Handle validation errors gracefully

Walk the details tree (each node’s errors array, recursing into properties) to show specific field errors to your users rather than generic error messages.

Last modified on August 8, 2026

API Documentation

Agent resources

Automations

Businesses

Contacts

Customers

Domains

Files

Messages

Operations

Tasks

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors

Validation Errors

Resource Errors

Domain Management Errors

Rate Limiting Errors

Server Errors

Handling Errors

Basic Error Handling

Retry with Exponential Backoff

Best Practices

​Error Response Format

​HTTP Status Codes

​Error Codes Reference

​Authentication Errors

​Validation Errors

​Resource Errors

​Domain Management Errors

​Rate Limiting Errors

​Server Errors

​Handling Errors

​Basic Error Handling

​Retry with Exponential Backoff

​Best Practices

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors

Validation Errors

Resource Errors

Domain Management Errors

Rate Limiting Errors

Server Errors

Handling Errors

Basic Error Handling

Retry with Exponential Backoff

Best Practices