Error codes

The following error codes can be returned by the Connect API.

If the service hits a fault it does not recognize, the response message is the bare string "Internal server error" with no code at all. This is expected. Contact support with the timestamp and the request you sent.

Error code	Definition	Applies to	Category
`ADDRESSABLE_ATTRIBUTE_IS_NOT_TEXT`	An attribute tied to a communication channel with `identifyAs.channels` must be of type TEXT.	Create a contact attribute	N/A
`ATTRIBUTES_PRECISION_LIMIT_EXCEEDED`	`decimalPrecision` must be between 0 and 14.	Create a contact attribute	N/A
`ATTRIBUTES_PRECISION_WRONG_TYPE`	`decimalPrecision` can only be set on attributes of type NUMBER.	Create a contact attribute	N/A
`ATTRIBUTE_ALREADY_EXISTS`	An attribute with the same name is already available in the audience.	Create a contact attribute	N/A
`ATTRIBUTE_DUPLICATE_PROVIDED`	The same attribute name appears more than once in one request.	Create contacts Update contacts Create a contact attribute Assign a contact attribute to another category	N/A
`ATTRIBUTE_HAS_SAME_NAME_AS_BEHAVIOURAL`	The name is already used by a behavioral attribute. Behavioral attribute names are reserved. Check them in the BEHAVIORAL_ATTRIBUTES data set.	Create a contact attribute	N/A
`ATTRIBUTE_IS_IMMUTABLE`	The attribute is read-only. Behavioral attributes are populated from signals and cannot be set through the API.	Create contacts Update contacts	N/A
`ATTRIBUTE_NAME_LENGTH_EXCEEDED`	Attribute names are limited to 255 characters.	Create a contact attribute	N/A
`ATTRIBUTE_NOT_DEFINED`	The mutation contains an attribute that is not available in the audience. Check the names of available attributes using the dataSets query.	Create contacts Update contacts Assign a contact attribute to another category	N/A
`BEHAVIORAL_ATTRIBUTES_NOT_FOUND`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Create contacts Update contacts	N/A
`CANNOT_REMOVE_LAST_ADDRESSABLE_FIELD`	The update would clear the contact's last remaining addressable attribute. Every contact must keep at least one email address or phone number.	Update contacts	N/A
`CHANNELS_ALREADY_ASSIGNED`	The channel is already assigned to another attribute in this audience. Each channel maps to one attribute.	Create a contact attribute	N/A
`CHANNELS_DUPLICATE_PROVIDED`	The same channel appears more than once in one request.	Create contacts Update contacts Update consent statuses for contacts Create a contact attribute	N/A
`CHANNEL_NOT_CONNECTED_WITH_ATTRIBUTE`	MOBILE is not backed by a contact attribute, so it cannot be used with `attributes(selectByChannel:)`. Use EMAIL, SMS or WHATSAPP.	Query contacts	N/A
`CHANNEL_NOT_DEFINED`	The channel you selected is not mapped to any attribute in this audience.	Query contacts	N/A
`CONSENT_GROUPS_FOR_DATASET_NOT_DEFINED`	There are no consent groups in the audience at the moment.	Create contacts Update contacts Update consent statuses for contacts	N/A
`CONSENT_GROUP_DUPLICATE_PROVIDED`	The same `consentGroupId` appears more than once in one request.	Create contacts Update contacts Update consent statuses for contacts	N/A
`CONSENT_GROUP_NOT_FOUND`	The `consentGroupId` does not exist in this audience. Check the available groups using the dataSets query.	Create contacts Update contacts Update consent statuses for contacts	N/A
`VALIDATION_FAILED`	An `addressable` selector was sent with no value. Provide a value or remove the selector.	Update contacts Delete contacts	`CONTACT_ADDRESSABLE_EMPTY_NOT_ALLOWED`
`VALIDATION_FAILED`	Use the `key` field instead of `addressable` to submit contact keys.	Update contacts Delete contacts	`CONTACT_ADDRESSABLE_IS_NOT_ADDRESSABLE`
`VALIDATION_FAILED`	Your audience has the Contact key attribute defined. You must use contact keys for identification. If you have a contact without a contact key, the only way to delete it is through the Connect application.	Delete contacts	`CONTACT_ADDRESSABLE_NOT_ALLOWED_WHEN_CONTACT_KEY_DEFINED`
`VALIDATION_FAILED`	An addressable value you specified is already in use. Revise the contacts before updating their attributes.	Update contacts	`CONTACT_ADDRESSABLE_SHOULD_BE_UNIQUE`
`CONTACT_DELETE_FAILED`	The contact hasn't been deleted due to an error. Try resubmitting your request.	Delete contacts	N/A
`RESOURCE_NOT_FOUND`	This contact has been merged into another contact and can no longer be written to. The error carries `rootContactId`. Repeat the request against that contact.	Create contacts Update contacts Delete contacts	`CONTACT_MERGED`
`VALIDATION_FAILED`	Every entry in one `updateContacts` call must identify contacts the same way. Do not mix `key` and `addressable` in a single mutation.	Update contacts	`CONTACT_SELECTOR_MIXING_NOT_ALLOWED`
`DATASET_TYPE_IS_IMMUTABLE`	This data set type cannot be changed or deleted. Behavioral attributes are managed by Connect.	Create a contact attribute Delete a reference set	N/A
`DATA_SET_BAD_REQUEST`	The data set cannot be modified. Some types, such as BEHAVIORAL_ATTRIBUTES, are read-only.	Create a contact attribute	N/A
`DATA_SET_DELETION_FAILED`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Delete a reference set	N/A
`DATA_SET_NOT_FOUND`	No data set exists with the `dataSetId` you supplied.	Query the audience Connect reference sets Disconnect reference sets Delete a reference set	N/A
`VALIDATION_FAILED`	The new attribute's name is already used as the default display text of another attribute in this catalog. Use a different name.	Add a custom attribute to the catalog	`DEFAULT_DISPLAY_TEXT_ALREADY_ASSIGNED`
`ENCOUNTERED_BIDIRECTIONAL_PAGINATION`	The pagination arguments point in two directions at once. Use `first` with `after`, or `last` with `before`. Never mix them.	Query contacts	N/A
`FAILED_CREATE_CONTACT`	The contact hasn't been added to the audience.	Create contacts Update contacts	N/A
`FAILED_DEPROVISION_REFERENCE_SET`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Delete a reference set	N/A
`FAILED_FETCH_CONSENT_EVENTS`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Query contacts	N/A
`FAILED_PROVISION_REFERENCE_SET`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Manage reference set attributes	N/A
`FAILED_TO_CONNECT_ASSOCIATIONS`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Connect reference sets	N/A
`FAILED_TO_CREATE_DATA_JOB`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Create a contact attribute	N/A
`FAILED_TO_DELETE_CONSENT_EVENTS`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Delete a reference set	N/A
`FAILED_TO_DISCONNECT_ASSOCIATIONS`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Disconnect reference sets	N/A
`FAILED_TO_UPDATE_DATASET_VIEW`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Create a contact attribute Delete a reference set	N/A
`FAILED_TO_UPDATE_DATA_SET`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Create a contact attribute	N/A
`IDENTIFIABLE_ATTRIBUTE_NOT_PROVIDED`	You must provide at least one addressable attribute for each contact (email or phone number).	Create contacts	N/A
`IDENTITY_ERROR`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Create contacts Update contacts Delete contacts	N/A
`ILLEGAL_STATE`	The request combines options that are mutually exclusive. In consent input, send either `channels` or `consentGroups`, not both. Otherwise this is a server-side error. Retry, and contact support if it persists.	Create contacts Update contacts Update consent statuses for contacts	N/A
`INPUT_VALIDATION_FAILED`	The request contains an argument the operation does not accept. The message names it. For example, `referenceSetRecords` cannot be requested from the `contacts` query.	Query contacts	N/A
`INTERNAL_SERVER_ERROR`	A server-side error. Retry the request. If it keeps failing, contact support with the timestamp and the request you sent.	Every request	N/A
`INVALID_ATTRIBUTE_NAME`	The attribute name contains characters that are not allowed.	Create a contact attribute	N/A
`VALIDATION_FAILED`	The `type` is not supported for this data set. Contact attributes accept TEXT, NUMBER, BOOLEAN and DATE. JSON and ARRAY are only available on the product catalog.	Create a contact attribute	`INVALID_ATTRIBUTE_TYPE`
`INVALID_ATTRIBUTE_VALUE`	The value fails the attribute's validation rules. Check `extensions.category` in the response for the reason, such as BOOLEAN_FORMAT, EMAIL_FORMAT, GENERAL_ERROR, INVALID_INPUT_TYPE, MAX_LENGTH, NUMERIC_FORMAT, NUMERIC_RANGE, PHONE_FORMAT, PHONE_MAX_LENGTH, PHONE_MIN_LENGTH or TIMESTAMP_FORMAT. Only the first invalid attribute is reported, so a request with several invalid values needs several attempts.	Create contacts Update contacts	BOOLEAN_FORMAT, EMAIL_FORMAT, GENERAL_ERROR, INVALID_INPUT_TYPE, MAX_LENGTH, NUMERIC_FORMAT, NUMERIC_RANGE, PHONE_FORMAT, PHONE_MAX_LENGTH, PHONE_MIN_LENGTH, TIMESTAMP_FORMAT
`INVALID_CURSOR`	The cursor is not valid. Pass back a cursor from `pageInfo` of a previous response, unchanged.	Query contacts	N/A
`INVALID_UPDATE_OPERATION_FOR_KEY`	The contact key attribute cannot be renamed or re-mapped with `mapAs`.	Assign a contact attribute to another category	N/A
`VALIDATION_FAILED`	`validateAs` is not accepted here. It is only available on product catalog attributes, and on a TEXT attribute the only permitted values are TEXT and URL.	Create a contact attribute	`INVALID_VALIDATE_AS`
`INVALID_VALUE_TYPE`	The value does not match the attribute's declared type. For example, text sent to a NUMBER attribute.	Create contacts Update contacts	N/A
`BAD_REQUEST`	A contact in your mutation already has a key. Once assigned, a contact key cannot be edited.	Update contacts	`KEY_CAN_NOT_BE_REASSIGNED`
`VALIDATION_FAILED`	This error appears if you try to add the Contact key attribute and assign it to a category other than Contact information. Change the category value to Contact information or remove the field from the mutation.	Create a contact attribute	`KEY_CATEGORY_NOT_ALLOWED`
`VALIDATION_FAILED`	The audience already has a key attribute.	Create a contact attribute	`KEY_CREATION_NOT_ALLOWED`
`KEY_DUPLICATE_PROVIDED`	Only one attribute can be the contact key, and the request marks more than one.	Create a contact attribute	N/A
`KEY_NOT_DEFINED`	You identified a contact by `key`, but this audience has no contact key attribute. Identify the contact by an addressable attribute, or add a key attribute to the audience first.	Update contacts Delete contacts	N/A
`KEY_SHOULD_BE_UNIQUE`	The mutation contains a contact key that is already present in the audience. You must use a unique value.	Create contacts Update contacts	N/A
`MALFORMED_CURSOR_VALUE`	The cursor could not be read. Pass back a cursor from `pageInfo` of a previous response, unchanged.	Query contacts	N/A
`MAP_AS_ALREADY_ASSIGNED`	The `mapAs` value is already used by another attribute in this audience.	Create a contact attribute	N/A
`MAP_AS_DUPLICATE_PROVIDED`	The same `mapAs` value appears more than once in one request.	Create a contact attribute	N/A
`MUTATION_SIZE_LIMIT_EXCEEDED`	The request exceeds the maximum batch size. `createContacts`, `updateContacts` and `deleteContacts` accept up to 25 contacts per call.	Delete contacts	N/A
`NAME_ALREADY_ASSIGNED`	The data set already has this name, so the request would not change anything.	Renaming a data set	N/A
`OKTA_ERROR`	Your request was not authorized. Check your API key and see Use the Connect API.	Every request	N/A
`OKTA_TIMEOUT`	Your request was not authorized. Check your API key and see Use the Connect API.	Every request	N/A
`ORG_ID_NOT_FOUND`	Your request was not authorized. Check your API key and see Use the Connect API.	Every request	N/A
`VALIDATION_FAILED`	The reference set is still connected to an audience or to another reference set. Disconnect it first, then delete it.	Delete a reference set	`REFERENCE_SET_CONNECTIONS_EXIST`
`REQUIRED_FIELD_NOT_PROVIDED`	A required field is missing. The message names the field.	Create contacts Update contacts	N/A
`RESERVED_ATTRIBUTE_NAME`	The name is reserved. Names beginning with an underscore are not allowed, nor are `mobile`, `dataSetType`, `subscriptionId` and `contactConsent`.	Create a contact attribute	N/A
`SUBSCRIPTION_NOT_FOUND`	Your request was not authorized. Check your API key and see Use the Connect API.	Every request	N/A
`UNAUTHORIZED`	Your request was not authorized. Check your API key and see Use the Connect API. On Delete a reference set, deleting this data set is not enabled for your subscription. Contact your account manager.	Every request Delete a reference set	N/A
`UNAUTHORIZED_FIELD_ACCESS`	The filter references a field that is not available to API callers. `contactId` cannot be used in `filter`. Identify contacts by contact key or an addressable attribute.	Query contacts	N/A
`UNSUPPORTED_OPERATION`	The operation is not available for this request. Removing contact attributes with `attributes.remove` is not supported for API-key callers, so use the Connect application instead. The `contacts` query only works on a contact data set. Data sets of type PRODUCT_INTEREST or CATEGORY_INTEREST cannot be updated or deleted through the API.	Query contacts Create a contact attribute Delete a reference set	N/A
`VALIDATION_FAILED`	An ARRAY attribute must declare `validateAs` to define the type of its elements.	Create a contact attribute	`VALIDATE_AS_NOT_DEFINED`
`VALIDATION_FAILED`	One or more attribute values failed validation. See `extensions.validationErrors` in the response for the affected attribute and the reason.	Create contacts Update contacts Delete contacts	N/A