> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope, and every error code the API answers with

A call that fails answers a `4xx` or `5xx` status and this body:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Target account not found",
    "request_id": "6f1c3a0e-2b0d-4c53-9a39-8f3c1d2e4b5a"
  }
}
```

| Field | What it is |
| - | - |
| `code` | What went wrong, from the list below. Branch on it. |
| `message` | A sentence you can show a person. It may change; never parse it. |
| `request_id` | The request's id, the same as the `X-Request-ID` response header. Send it to support with a question about a call. |
| `details` | Developer text. Never set in production. |

Every code is in `UPPER_SNAKE` case and means the same on every operation. New codes may be added;
a code is never renamed within `/v2`. Treat a code you do not know by its status: retry a `5xx`
or a `429` later, fix the request on another `4xx`.

## Status codes

| Status | Meaning | Retry? |
| - | - | - |
| `400` | The request is not valid: a parameter, a body field or its JSON. | No, fix the request |
| `401` | No credential, or one that is not valid. | No |
| `402` | Out of credits for what was asked. | After topping up |
| `403` | The credential is valid but may not do this, or the plan does not include it. | No |
| `404` | The record or the route does not exist in your tenant. | No |
| `409` | The request conflicts with the current state: a duplicate, a run in progress. | After the state changes |
| `413` | The body is too large. | No, send less |
| `422` | The request is well formed but cannot be done as asked. | No, fix the request |
| `429` | Too many requests. Wait, then retry; honour `Retry-After` when it is set. | Yes |
| `500` | Clustr failed. | Yes, with backoff |
| `502`, `503`, `504` | A service Clustr depends on (your CRM, a data provider) failed or did not answer. | Yes, with backoff |

## Codes

### Requests

| Code | Meaning |
| - | - |
| `BAD_REQUEST` | The request is not valid; `message` says what. |
| `VALIDATION_ERROR` | A field fails its rule (a required field is missing, a value is out of range). |
| `INVALID_REQUEST` | The request cannot be read as sent. |
| `INVALID_INPUT` | A value is not one the operation takes. |
| `INVALID_BODY` | The body is not the JSON the operation reads. |
| `PARSE_ERROR` | The body is not JSON. |
| `INVALID_FIELD` | A field name or value is not one the operation knows. |
| `MISSING_FIELDS` | A required field is missing. |
| `MISSING_HEADER` | A required header is missing. |
| `INVALID_UUID` | An id is not a valid id. |
| `INVALID_BOOLEAN` | A value that must be `true` or `false` is neither. |
| `INVALID_URL` | A URL is not valid. |
| `INVALID_WEBSITE_URL` | A website is not a valid URL or domain. |
| `INVALID_LINKEDIN_URL` | A LinkedIn URL is missing or is not the kind of page the operation needs (a company page, a profile). |
| `NO_LINKEDIN_URL` | The record has no LinkedIn URL to work from. |
| `NO_WEBSITE` | The company has no website to work from. |
| `INVALID_COMPANY_NAME` | The company name is empty or not usable. |
| `INVALID_SCHEDULE` | A schedule is not valid. |
| `INVALID_SETTINGS` | A settings value is not valid. |
| `INVALID_MATCHING_SETTINGS` | The matching settings are not valid. |
| `INVALID_MAPPING` | A field mapping is not valid. |
| `INVALID_OBJECT_TYPE` | The object type is not one the operation takes. |
| `UNSUPPORTED_OBJECT_TYPE` | The object type is not supported for this CRM. |
| `UNSUPPORTED_RESOURCE_TYPE` | The resource type is not supported. |
| `INVALID_TARGET_LIST` | The target list is not valid. |
| `INVALID_CUSTOMER_RULE` | The customer rule is not valid for this CRM: no condition, a property that does not exist, or values that do not match it. |
| `INVALID_EVENT` | The event is not one Clustr knows. |
| `INVALID_ENDPOINT` | The endpoint URL is not valid. |
| `INVALID_BUCKET` | The bucket is not one the operation takes. |
| `INVALID_TENANT_ID` | The tenant id is not valid. |
| `MISSING_TENANT_ID` | The request names no tenant. |
| `MISSING_USER_ID` | The request names no user. |
| `MISSING_JOB_ID` | The request names no job. |
| `MISSING_OBJECT_ID` | The request names no object. |
| `MISSING_PORTAL_ID` | The request names no CRM portal. |
| `UNKNOWN_FEATURE` | The feature is not one Clustr knows. |
| `UNKNOWN_PROVIDER` | The provider is not one Clustr knows. |
| `UNSUPPORTED_PROVIDER` | The provider is not supported by this operation. |
| `UNSUPPORTED_FLOW` | The flow is not supported. |
| `UNSUPPORTED_MEDIA_TYPE` | The body's `Content-Type` is not one the operation takes. |
| `UNPROCESSABLE_ENTITY` | The request is well formed but cannot be done as asked. |
| `METHOD_NOT_ALLOWED` | The route does not take this method. |
| `ROUTE_NOT_FOUND` | No operation has this path. |
| `BODY_TOO_LARGE` | The body is too large. |
| `PAYLOAD_TOO_LARGE` | The body is too large. |
| `BULK_PUSH_TOO_LARGE` | Too many records in one push; send fewer. |
| `HEADERS_TOO_LARGE` | The headers are too large. |
| `TOO_MANY_HEADERS` | The request sends too many headers. |
| `URL_TOO_LONG` | The URL is too long. |
| `REDIRECT_REFUSED` | The return address is not one of the app's. |

### Credentials and access

| Code | Meaning |
| - | - |
| `UNAUTHORIZED` | No credential, or one that is not valid. |
| `AUTH_FAILED` | The credential could not be verified. |
| `INVALID_TOKEN` | The token is not valid or has expired. |
| `NO_TOKEN` | The request carries no token. |
| `INVALID_CREDENTIALS` | The credentials are wrong. |
| `INVALID_SIGNATURE` | A signed request's signature does not match. |
| `KEY_NOT_REGISTERED` | The key is not registered. |
| `AUTH_METHOD_UNSUPPORTED` | This operation does not take this kind of credential. |
| `AUTH_CONTEXT_ERROR` | Clustr could not read who is calling. |
| `AUTHORIZATION_UNAVAILABLE` | Clustr could not check the caller's permissions; try again. |
| `FORBIDDEN` | The caller may not do this. |
| `INSUFFICIENT_PERMISSION` | The person's role does not have the permission this needs. |
| `ADMIN_REQUIRED` | Only an admin of the tenant may do this. |
| `STAFF_REQUIRED` | Only Clustr staff may do this. |
| `USER_NOT_AUTHORIZED` | The user is not allowed in this tenant. |
| `TENANT_MISMATCH` | The record belongs to another tenant. |
| `TENANT_LOOKUP_FAILED` | Clustr could not find the caller's tenant; try again. |
| `NO_ORG` | The tenant has no organization. |
| `ORG_LIMIT_EXCEEDED` | The organization is at its limit. |

### Plan, credits and limits

| Code | Meaning |
| - | - |
| `FEATURE_NOT_ENABLED` | The plan does not include this add-on; `message` names it. |
| `NOT_ENABLED` | The feature is turned off for the tenant. |
| `NO_PACKAGE` | The tenant has no package that includes this. |
| `ENTITLEMENT_UNAVAILABLE` | Clustr could not check the plan; try again. |
| `INSUFFICIENT_CREDITS` | Not enough credits for what was asked. |
| `PAYMENT_REQUIRED` | The plan or the credits do not cover this. |
| `NO_SLOT` | Every slot is in use; free one or raise the limit. |
| `RATE_LIMITED` | Too many requests; wait, then retry. |
| `RATE_LIMIT_EXCEEDED` | Too many requests; wait, then retry. |
| `REFRESH_RATE_LIMITED` | A refresh ran too recently; try later. |
| `SETUP_RATE_LIMITED` | Setup ran too recently; try later. |
| `TOO_SOON` | The same action ran too recently; try later. |
| `RESOURCE_EXHAUSTED` | A limit is reached for now; try later. |
| `CRM_DAILY_LIMIT` | The CRM's daily limit is reached; try tomorrow. |

### Records and state

| Code | Meaning |
| - | - |
| `NOT_FOUND` | The record does not exist in your tenant. |
| `COMPANY_NOT_FOUND` | The company does not exist. |
| `COMPANY_NOT_RESOLVED` | Clustr could not tell which company this is. |
| `PROFILE_NOT_RESOLVED` | Clustr could not tell whose LinkedIn profile this is. |
| `PERSON_LEFT` | The person no longer works at the company. |
| `JOB_NOT_FOUND` | The job does not exist. |
| `MAPPING_NOT_FOUND` | The mapping does not exist. |
| `TARGET_LIST_NOT_FOUND` | The CRM list does not exist. |
| `TARGET_LIST_NOT_BINDABLE` | The CRM list cannot be bound to the target accounts. |
| `MATCHING_VERSION_NOT_FOUND` | That version of the matching settings does not exist. |
| `NO_TEAM_FOUND` | No team was found for the company. |
| `NO_BUYER_TITLES` | The tenant has no buyer titles yet. |
| `CONFLICT` | The request conflicts with the current state. |
| `ALREADY_LISTED` | The company is already on the customer list. |
| `CRM_ROW` | The record is on the list because your CRM puts it there: change it in the CRM, or exclude it. |
| `NO_MATCH_KEY` | The company has no LinkedIn page or domain to match on yet. |
| `COMPETITOR_EXISTS` | The tenant already tracks this competitor. |
| `MATCHING_SETTINGS_CONFLICT` | The matching settings changed since you read them; read them again. |
| `SYNC_IN_PROGRESS` | A sync is already running; wait for it to end. |
| `EXPORT_IN_FLIGHT` | An export is already running; wait for it to end. |
| `CANCELLED` | The work was cancelled. |
| `NOT_APPLIED` | The change was not applied. |
| `NOT_RETRYABLE` | This failure cannot be retried. |
| `NOT_REVERTABLE` | This change cannot be undone. |
| `REVERT_CONFLICT` | The record changed since; the change cannot be undone. |
| `REVERT_EXPIRED` | The change is too old to undo. |
| `REVERT_BATCH_UNAVAILABLE` | The batch cannot be undone now; try again. |
| `FINDING_NOT_APPLICABLE` | The cleaning finding no longer applies. |
| `DUPLICATE_ALREADY_RESOLVED` | The duplicate was already merged or dismissed. |
| `NOT_DUPLICATE_CLUSTER` | The records are not a group of duplicates. |
| `FAMILY_CLUSTER` | The records are related companies, not duplicates. |
| `REPORT_ONLY_DUPLICATE` | The duplicate is reported only, never merged by Clustr. |
| `NOT_AUTO_SAFE` | The merge needs a person to approve it. |
| `MERGES_DISABLED` | Merging is turned off for the tenant. |
| `MERGE_UNRESOLVED` | The merge could not be worked out. |
| `MERGE_UNSUPPORTED` | The CRM does not support this merge. |
| `RESEARCH_NOT_STARTED` | The account research did not start. |
| `PRIVATE_CHANNEL_NEEDS_INVITE` | Invite the Clustr app to the private Slack channel first. |
| `ESCALATION_EMAIL_DISABLED` | Escalation emails are turned off. |
| `NOT_CONFIGURED` | The feature is not set up yet. |

### Connected tools

| Code | Meaning |
| - | - |
| `NOT_CONNECTED` | The integration is not connected. |
| `NO_CONNECTION` | The tenant has no connection for this. |
| `CRM_NOT_CONNECTED` | No CRM is connected. |
| `CRM_NOT_ACTIVE` | The CRM connection is not active. |
| `HUBSPOT_NOT_CONNECTED` | HubSpot is not connected. |
| `SALESFORCE_NOT_CONNECTED` | Salesforce is not connected. |
| `ATTIO_NOT_CONNECTED` | Attio is not connected. |
| `ATTIO_WORKSPACE_NOT_FOUND` | The Attio workspace (Attio's own word) is not found. |
| `SALESFORCE_ORG_NOT_FOUND` | The Salesforce org is not found. |
| `UNKNOWN_PORTAL` | The CRM portal is not one Clustr knows. |
| `PORTAL_TENANT_MISMATCH` | The CRM portal belongs to another tenant. |
| `CRM_RECONNECT_REQUIRED` | Reconnect the CRM. |
| `INTEGRATION_REAUTH_REQUIRED` | Reconnect the integration. |
| `CRM_CREDENTIAL_EXPIRED` | The CRM connection expired; reconnect it. |
| `CRM_SCOPE_MISSING` | The CRM connection lacks a permission this needs; reconnect it. |
| `CRM_WRITE_DISABLED` | Writing to the CRM is turned off. |
| `SYNC_PROPERTIES_DISABLED` | Syncing CRM properties is turned off. |
| `CRM_CAPABILITY_UNSUPPORTED` | The CRM has no counterpart for this; `message` names the CRM. |
| `CRM_LISTS_UNSUPPORTED` | The CRM has no lists. |
| `CRM_RATE_LIMITED` | The CRM is limiting requests; try later. |
| `CRM_UNAVAILABLE` | The CRM could not be reached; try again. |
| `CRM_SCHEMA_UNAVAILABLE` | The CRM's fields could not be read; try again. |
| `CRM_VALUES_UNAVAILABLE` | The CRM field's values could not be read; try again. |
| `CUSTOMERS_UNAVAILABLE` | The customer list could not be read or cleared; try again. |
| `HUBSPOT_UPSTREAM_ERROR` | HubSpot answered with an error. |
| `SLACK_REJECTED` | Slack refused the request. |
| `NO_ACTIVE_WAREHOUSE` | No data warehouse is connected. |
| `DATABASE_NOT_FOUND` | The warehouse database is not found. |
| `DATASET_NOT_FOUND` | The BigQuery dataset is not found. |
| `PROJECT_NOT_FOUND` | The project is not found. |
| `TABLE_SHAPE_MISMATCH` | The warehouse table does not have the columns Clustr writes. |
| `SUPABASE_NEEDS_POOLER` | Use the Supabase pooler's connection string. |
| `BIGQUERY_ERROR` | BigQuery answered with an error. |
| `SNOWFLAKE_ERROR` | Snowflake answered with an error. |
| `FULLENRICH_API_ERROR` | The enrichment provider answered with an error. |
| `FULLENRICH_UNEXPECTED_ERROR` | The enrichment provider answered something unexpected. |

### Failures

These are Clustr's or a service's failures, not the request's. Retry with backoff.

| Code | Meaning |
| - | - |
| `INTERNAL_ERROR` | Clustr failed. |
| `UNKNOWN_ERROR` | Clustr failed for a reason it could not name. |
| `PANIC_RECOVERED` | Clustr failed. |
| `PROCESSING_ERROR` | The work failed while running. |
| `REQUEST_FAILED` | A call Clustr made failed. |
| `API_REQUEST_FAILED` | A call Clustr made failed. |
| `RESPONSE_READ_FAILED` | Clustr could not read an answer it got. |
| `UPSTREAM_ERROR` | A service Clustr depends on answered with an error. |
| `UPSTREAM_UNAVAILABLE` | A service Clustr depends on is not available. |
| `BAD_GATEWAY` | A service Clustr depends on answered with an error. |
| `GATEWAY_TIMEOUT` | A service Clustr depends on did not answer in time. |
| `SERVICE_UNAVAILABLE` | Clustr is not available right now. |
| `SERVICE_UNREACHABLE` | A part of Clustr could not be reached. |
| `SERVICE_NOT_FOUND` | A part of Clustr could not be found. |
| `UNAVAILABLE` | This is not available right now. |
| `CLIENT_CLOSED_REQUEST` | The caller closed the connection before the answer. |
| `QUEUE_UNAVAILABLE` | The work queue is not available. |
| `RATE_LIMITER_INIT_FAILED` | Clustr could not check the rate limit. |
| `JOB_CLIENT_NOT_CONFIGURED` | The job service is not set up. |
| `JOB_CREATION_FAILED` | The job could not be created. |
| `TASK_CREATION_FAILED` | The task could not be created. |
| `LOAD_FAILED` | Loading failed. |
| `SAVE_FAILED` | Saving failed. |
| `SEARCH_FAILED` | The search failed. |
| `SETUP_FAILED` | Setup failed. |
| `FIRE_FAILED` | The automation could not run. |
| `EXPORT_FAILED` | The export failed. |
| `EXPORT_UNAVAILABLE` | Exports are not available right now. |
| `WEBHOOK_UNAVAILABLE` | The webhook could not be reached. |
| `EMAIL_NOTIFIER_UNAVAILABLE` | Email could not be sent. |
| `VERIFICATION_UNAVAILABLE` | The check could not run. |
| `REFRESH_UNAVAILABLE` | The refresh is not available right now. |
| `SYNC_UNAVAILABLE` | The sync is not available right now. |
| `SYNC_STATUS_UNAVAILABLE` | The sync's status could not be read. |
| `VALUES_FAILED` | The values could not be read. |
| `VALUES_UNAVAILABLE` | The values are not available right now. |
| `BUYER_TITLES_UNAVAILABLE` | The buyer titles could not be read. |
| `TARGET_ACCOUNTS_UNAVAILABLE` | The target accounts could not be read. |
| `CLEANING_REPORT_FAILED` | The CRM cleaning report failed. |
| `CLEANING_REPORT_UNAVAILABLE` | The CRM cleaning report is not available yet. |
| `PROPERTY_INSIGHTS_FAILED` | The CRM property insights failed. |
| `PROPERTY_INSIGHTS_UNAVAILABLE` | The CRM property insights are not available yet. |
| `DUPLICATE_CHECK_FAILED` | The duplicate check failed. |
| `COMPETITOR_READ_FAILED` | The competitor could not be read. |
| `COMPETITOR_RUN_FAILED` | The competitor monitoring run failed. |

## A streamed assistant turn

A turn streamed as Server-Sent Events (`POST /v2/assistant/messages` with `stream: true`) answers
`200` before it runs. A failure after that is an `error` event carrying the same `code` and a
sentence in `error`, and ends the stream.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.