4xx or 5xx status and this body:
{
"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. |
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.