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"
  }
}

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

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

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

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

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

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

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

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

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

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