Errors

When a request fails, the response includes "ok": false and an error object with a machine-readable code and a human-readable message.

Error Response Format

{
  "ok": false,
  "error": {
    "code": "contacts.not_found",
    "message": "Contact not found"
  }
}

HTTP Status Codes

Status	Meaning
`200`	Success
`400`	Bad request — invalid parameters
`401`	Unauthorized — missing or invalid token
`403`	Forbidden — account locked or insufficient permissions
`404`	Not found
`429`	Rate limit exceeded
`500`	Internal server error

Error Codes by Domain

Authentication

Code	Description
`auth.required`	No Authorization header provided
`auth.invalid_request`	Malformed request body
`auth.invalid_credentials`	Wrong email or password
`auth.email_taken`	Email already registered
`auth.invalid_token`	Expired or invalid token
`auth.deactivated`	User account has been deactivated
`auth.internal`	Server error during authentication

Contacts

Code	Description
`contacts.invalid_request`	Malformed request body
`contacts.invalid_id`	Invalid UUID format
`contacts.not_found`	Contact does not exist
`contacts.first_name_required`	First name is required for creation
`contacts.invalid_company_id`	Referenced company does not exist
`contacts.invalid_source_id`	Referenced source does not exist
`contacts.invalid_custom_fields`	Custom field values don’t match definitions
`contacts.internal`	Server error

Companies

Code	Description
`companies.invalid_request`	Malformed request body
`companies.invalid_id`	Invalid UUID format
`companies.not_found`	Company does not exist
`companies.invalid_custom_fields`	Custom field values don’t match definitions
`companies.internal`	Server error

Projects

Code	Description
`projects.invalid_request`	Malformed request body
`projects.invalid_id`	Invalid UUID format
`projects.not_found`	Project does not exist
`projects.name_required`	Name is required for creation
`projects.invalid_stage`	Stage must be: proposal, active, review, complete, archived
`projects.invalid_company_id`	Referenced company does not exist
`projects.invalid_assigned_to`	Referenced user does not exist
`projects.invalid_custom_fields`	Custom field values don’t match definitions
`projects.internal`	Server error

Activities

Code	Description
`activities.invalid_request`	Malformed request body
`activities.invalid_id`	Invalid UUID format
`activities.invalid_type`	Type must be: call, email, meeting
`activities.entity_required`	Must provide at least one of contact_id, company_id, or project_id
`activities.invalid_metadata`	Metadata doesn’t match schema for the activity type
`activities.not_found`	Activity does not exist
`activities.internal`	Server error

Sources

Code	Description
`sources.invalid_request`	Malformed request body
`sources.invalid_id`	Invalid UUID format
`sources.not_found`	Source does not exist
`sources.name_required`	Name is required
`sources.internal`	Server error

Webhooks

Code	Description
`webhooks.invalid_request`	Malformed request body
`webhooks.invalid_id`	Invalid UUID format
`webhooks.not_found`	Webhook endpoint does not exist
`webhooks.url_required`	URL is required
`webhooks.invalid_url`	URL must be a valid HTTPS URL
`webhooks.internal`	Server error

Custom Fields

Code	Description
`custom_fields.invalid_request`	Malformed request body
`custom_fields.invalid_id`	Invalid UUID format
`custom_fields.not_found`	Custom field definition does not exist
`custom_fields.invalid_entity_type`	Entity type must be: contact, company
`custom_fields.label_required`	Label is required
`custom_fields.invalid_field_type`	Field type must be: text, number, date, boolean, enum
`custom_fields.options_required`	Enum fields require an options array
`custom_fields.internal`	Server error

OAuth

Code	Description
`oauth.invalid_request`	Malformed request body
`oauth.unsupported_grant_type`	Only `client_credentials` is supported
`oauth.missing_credentials`	Missing client_id or client_secret
`oauth.invalid_client`	Invalid credentials or app has been revoked
`oauth.internal`	Server error

OAuth Apps

Code	Description
`oauth_apps.invalid_request`	Malformed request body
`oauth_apps.invalid_id`	Invalid UUID format
`oauth_apps.not_found`	OAuth app does not exist
`oauth_apps.name_required`	Name is required
`oauth_apps.internal`	Server error

Imports

Code	Description
`imports.invalid_request`	Malformed request body
`imports.invalid_id`	Invalid UUID format
`imports.not_found`	Import job does not exist
`imports.model_type_required`	Model type is required
`imports.file_name_required`	File name is required
`imports.invalid_model_type`	Model type must be: contacts, companies, sources
`imports.internal`	Server error

Error Handling Best Practices

Always check ok — don’t assume success based on HTTP status alone
Use the code for logic — error codes are stable; messages may change
Handle auth.invalid_token — refresh your token and retry the request once
Retry transient failures — back off and retry on network errors and 5xx responses (see Retrying requests)
Log the full error — include both code and message for debugging

Retrying requests

Some failures are transient and safe to retry; others are deterministic and will fail again until you fix the request.

Safe to retry (with backoff):

Network/connection errors and timeouts
500 responses (*.internal) — a transient server-side error

Do not retry as-is — fix the request first:

400 (validation), 403 (forbidden), 404 (not found) — deterministic; the same request will fail again
401 (auth.invalid_token) — refresh your access token, then retry once

Use exponential backoff with jitter and cap the number of attempts:

import time, random

def with_retry(call, max_attempts=4):
    for attempt in range(max_attempts):
        resp = call()
        if resp.status_code < 500:
            return resp                      # success or a deterministic error
        if attempt == max_attempts - 1:
            return resp
        time.sleep(min(2 ** attempt, 8) + random.random())  # 1s, 2s, 4s … + jitter

Write operations are not guaranteed idempotent. If a create/update times out, verify whether it applied (e.g. via a -list or -get) before retrying so you don’t create duplicates.