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
`409`	Conflict	Request conflicts with existing state (e.g., a name that’s already in use)
`422`	Unprocessable Entity	The request is well-formed but cannot be acted on
`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
`BUSINESS_AGREEMENT_REQUIRED`	403	An owner or admin has not accepted the business agreement in Bizzy

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

Every request with a key for a business is refused with BUSINESS_AGREEMENT_REQUIRED until an owner or admin accepts the business agreement in Bizzy, including after a new version needs accepting. The key works again within a minute of acceptance.

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.

Automation errors

Code	Status	Description
`AUTOMATION_AGENT_NOT_FOUND`	422	`agentId` does not name an active agent in your organization
`AUTOMATION_DEFAULT_AGENT_REQUIRED`	422	`agentId` was omitted and your organization has no active default agent
`AUTOMATION_ACTIVATION_REQUIRES_APPROVAL`	409	Only an active or paused automation can be paused or resumed — approve it first
`AUTOMATION_STATUS_CONFLICT`	409	The automation’s status changed while the request was being processed

{
    "error": {
        "code": "AUTOMATION_AGENT_NOT_FOUND",
        "message": "Agent 123e4567-e89b-12d3-a456-426614174000 is not an active agent in this organization"
    }
}

Email template errors

Code	Status	Description
`EMAIL_TEMPLATE_NAME_TAKEN`	409	A template with this name already exists in your organization

{
    "error": {
        "code": "EMAIL_TEMPLATE_NAME_TAKEN",
        "message": "An email template named \"Welcome email\" already exists"
    }
}

Domain Management Errors

Code	Status	Description
`REGISTRAR_UNSUPPORTED_OPERATION`	422	The requested operation isn’t available for this domain
`REGISTERED_DOMAIN_NOT_EXPIRED`	409	A registered domain can only be deleted after its registration expires
`REGISTERED_DOMAIN_RENEWAL_IN_FLIGHT`	409	A renewal is already queued or running for the domain
`REGISTERED_DOMAIN_TRANSFER_IN_FLIGHT`	409	A transfer to another registrar is under way. Until it finishes or is cancelled, you can’t delete or renew the domain, add a subdomain, change its transfer lock, or change its registrant’s name, organization, or email
`REGISTERED_DOMAIN_DNS_NOT_EMPTY`	409	The domain’s DNS zone still holds records; `details.blockingRecords` lists them
`DOMAIN_AGREEMENTS_REQUIRED`	409	A business owner or admin must accept the current domain agreements before a registration or renewal; `details.acceptanceUrl` is where, `details.agreements` lists them. Nothing was charged
`DOMAIN_AGREEMENTS_UNAVAILABLE`	503	The agreements for that domain ending aren’t available yet — try again later
`DOMAIN_SUBDOMAINS_EXIST`	409	Remove the domain’s subdomains before deleting it; the message names them
`DOMAIN_ALREADY_EXISTS`	409	The name is already in the organization
`DOMAIN_PARENT_EXISTS`	409	The name is one label under a domain you already have; add it with `POST /v1/domains/{id}/subdomains` — `details.parentDomainId` names the parent
`DOMAIN_NESTING_UNSUPPORTED`	409	The name sits under a domain you already have but cannot be its subdomain — the held domain is itself a subdomain, or the name is more than one label under it. `details.parentDomainId` names the held domain
`DOMAIN_NOT_APEX`	409	The parent is itself a subdomain; subdomains hang directly off an apex domain
`DOMAIN_NOT_VERIFIED`	409	Verify the parent domain before adding subdomains to it
`SUBDOMAIN_NOT_UNDER_PARENT`	400	A subdomain’s name must be exactly one label under its parent

{
    "error": {
        "code": "REGISTRAR_UNSUPPORTED_OPERATION",
        "message": "This operation (registrant contact updates) is not available",
        "details": {
            "operation": "registrant contact updates"
        }
    }
}

A small number of management operations aren’t available for every domain — for example, some registrations don’t support changing the registrant contact after purchase. When that happens the request returns 422 with this code and the affected operation.

DNS record content

A DNS record’s content must match its type. A mismatch returns 400 with VALIDATION_ERROR.

Type	Expected `content`
`A`	An IPv4 address, e.g. `192.0.2.1`
`AAAA`	An IPv6 address, e.g. `2001:db8::1`
`CNAME`	A domain name, e.g. `target.example.com`
`MX`	A mail server domain, e.g. `mail.example.com`
`NS`	A nameserver domain, e.g. `ns1.example.com`
`CAA`	A policy, e.g. `0 issue "letsencrypt.org"`
`TXT`	Any non-empty text
`SRV`	Any non-empty text

content is limited to 2048 characters for every record type — long enough for a DKIM key. MX and SRV records also require priority.

Idempotency errors

Code	Status	Description
`IDEMPOTENCY_KEY_IN_FLIGHT`	409	The original request with this key is still running
`IDEMPOTENCY_KEY_REUSED`	422	This key was already used for a different request

{
    "error": {
        "code": "IDEMPOTENCY_KEY_REUSED",
        "message": "This Idempotency-Key was already used for a different request. Retries must resend the identical request; use a new key for a new operation."
    }
}

A retry must resend the identical request. See Idempotency for the full behavior.

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. When you retry a POST, send an Idempotency-Key so a request that already succeeded is replayed rather than performed twice.

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.

API Documentation

Agent resources

Automations

Businesses

Contacts

Customers

Domains

Email Templates

Files

Invoices

Invoice Line Items

Invoice Payments

Messages

Operations

Properties

Tasks

Error Response Format

HTTP Status Codes

Error Codes Reference

Authentication Errors

Validation Errors

Resource Errors

Automation errors

Email template errors

Domain Management Errors

DNS record content

Idempotency 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

​Automation errors

​Email template errors

​Domain Management Errors

​DNS record content

​Idempotency 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

Automation errors

Email template errors

Domain Management Errors

DNS record content

Idempotency errors

Rate Limiting Errors

Server Errors

Handling Errors

Basic Error Handling

Retry with Exponential Backoff

Best Practices