Errors

Every error response has a JSON body with an error member naming the code, so branch on the code rather than on the message. Some carry more members that help you fix the request, such as the property or items at fault; the operation's reference page says which. A response without a body, such as a plain 404, means the thing you named does not exist or the key cannot see it.

Content Delivery API

Code	Status	Meaning	Returned by
audiences_not_in_ctx	400	ctx carries audiences.	Resolve a path
category_not_in_group	400	the category belongs to a different group from the one the filter is scoped to.	Query a stream
contract_not_in_sources	400	the contract exists, but this stream does not cover it.	Query a stream
environment_mismatch	400	env names a different delivery environment than the key's.	List published sites, Get the locale tree, Get sitemap data
invalid_context	400	ctx is not a valid context bag.	Get a published component
invalid_cursor	400	the cursor is malformed or belongs to a different order; restart from the first page.	List published components, Query a stream
locale_not_addressable	400	the site takes its locale from the address.	Resolve a path
preview_raw_unsupported	400	raw=true with a preview session.	Resolve a path
tree_too_large	400	over 5,000 nodes; narrow it with from, include or maxDepth.	Query the page tree
unknown_category	400	no category has this path or id.	List published components, Query a stream
unknown_contract	400	no contract has this id or external id.	List published components, Query a stream
unknown_filter_field	400	no field, an undeclared one, or the full-text filter. validation_failed, unknown_category, category_not_in_group, unknown_contract and contract_not_in_sources as for the stream.	Get a stream facet
validation_failed	400	an unsupported parameter value.	Resolve a path, Query the page tree, Get a published component, List published components, Query a stream
invalid_preview_token	401	the token is spent, expired, unknown, or was minted for another delivery environment.	Exchange a preview token
missing_api_key invalid_api_key	401	no key was sent, or it is unknown, revoked or expired.	Any operation
app_not_available	403	Content is not enabled for the organization.	Any operation
key_realm_mismatch	403	the key is limited to one realm and the site named by site belongs to a realm outside it. A key with no realm serves every site; one with a realm serves the sites that realm and the realms below it own.	Get the locale tree, Resolve a path, Query the page tree, Get sitemap data
members_only	403	the page is restricted and the request carries no valid claim for its audience (or one without the verification the audience requires). The body is { "error": "members_only", "gate": { "audienceId", "access": "verified" | "open", "door": { "kind": "signIn" | "form" | "none", "formId"? } }, "unlock": { … } }, where unlock is the Experience to show instead (resolved like any page, in the request's locale) or { "kind": "builtin", "heading", "message", "doorLabel" } when none is chosen. It never contains the withheld page.	Resolve a path
origin_denied ip_denied	403	a browser-safe key was used from an origin or address outside its restrictions.	Any operation
preview_site_mismatch	403	the path is in a different site from the page being previewed.	Resolve a path
scope_denied	403	the key lacks this route's scope.	Any operation
node_not_found	404	from names nothing published in that site.	Query the page tree
not_published	404	no published component has this id or external id.	Get a published component
path_not_found	404	nothing is published at this path.	Resolve a path
site_not_found	404	no site matches site or host.	Resolve a path, Query the page tree, Get sitemap data
unknown_stream	404	no stream has this external id or id.	Query a stream, Get a stream facet
too_many_failed_authentications	429	too many bad keys from this address.	Any operation

Assets Delivery API

Code	Status	Meaning	Returned by
unknown_parameter	400	this read takes no locale; use GET /assets/{id}/rendition for one locale.	Get an asset with every rendition
validation_failed	400	cursor is not one this API returned.	List and search assets
missing_api_key invalid_api_key	401	no key was sent, or it is unknown, revoked or expired, or its channel no longer exists.	Any operation
payment_required	402	the organization's subscription needs attention.	Any operation
app_not_available	403	Assets is not enabled for the organization.	Any operation
members_only	403	the asset is restricted to an audience the visitor's token does not grant. The body names the asset's kind and nothing else.	Get an asset with every rendition, Get an asset for one locale
origin_denied ip_denied	403	the key was used from an origin or address outside its restrictions.	Any operation
scope_denied	403	the key lacks assets.delivery.read.	Any operation
not_found	404	there is no such asset, or it is outside the key's channel.	Get an asset with every rendition, Get an asset for one locale
too_many_failed_authentications	429	too many bad keys from this address; Retry-After says how long to wait.	Any operation

Data Delivery API

Code	Status	Meaning	Returned by
invalid_generations	400	generations is not a whole number from 0 to 5.	Get a record by key
invalid_search invalid_cursor	400	the cursor belongs to a different query.	List, filter and search records
missing_api_key invalid_api_key	401	no key was sent, or it is unknown, revoked or expired, or its partition binding was removed.	Any operation
payment_required	402	the organization's subscription needs attention.	Any operation
app_not_available	403	Data is not enabled for the organization.	Any operation
origin_denied ip_denied	403	the key was used from an origin or address outside its restrictions.	Any operation
scope_denied	403	the key lacks data.delivery.read.	Any operation
model_not_found	404	no model has that key, or the key may not read it.	List, filter and search records
record_not_found	404	there is no such record, or the key may not read it.	Get a record by key
rate_limited	429	the key spent its requests-per-minute budget; Retry-After says how long to wait.	Any operation
too_many_failed_authentications	429	too many bad keys from this address.	Any operation

Content Management API

Code	Status	Meaning	Returned by
abstract_contract	400	an abstract contract cannot be instantiated; use one that inherits from it.	Create a component
ambiguous_delivery_target	400	it publishes to several, listed in mappedDeliveryEnvironmentIds; name one as deliveryEnvironmentId.	Plan a publish, Publish content, Resolve a draft preview, Preview a stream
category_not_in_group	400	the category belongs to a different group from the one the filter is scoped to.	Preview a stream
cycle	400	the new parent is the folder itself or one of its descendants.	Rename or move a folder, Update or move a category
delivery_target_not_mapped	400	deliveryEnvironmentId is not a delivery environment this environment publishes to.	Plan a publish, Publish content, Resolve a draft preview, Preview a stream
folder_contract_constraint_violation	400	the folder does not allow components of this contract.	Create a component, Update a component
incomplete_sibling_set	400	orderedNodeIds does not match the parent's current children; re-read them with GET /experience/nodes/{id}/children and retry.	Reorder sibling nodes
invalid_context	400	ctx is not a valid context bag.	Resolve a draft preview
invalid_cursor	400	the cursor is malformed or belongs to a different listing; restart from the first page.	List the environment's items
invalid_filter_value	400	a date value is not YYYY-MM.	Preview a stream
invalid_json	400	the body is not valid JSON.	Export a bundle, Plan an import, Import a bundle, Plan a publish, Publish content
invalid_move	400	the node is a site root, or the new parent is the node itself or one of its descendants.	Move a node
invalid_publish_status	400	a publishStatus is not one of the four statuses.	List components
invalid_redirect_target	400	a node cannot redirect to itself.	Set a node's payload
invalid_request	400	componentIds is empty or has more than 200 ids.	Move components to a folder
invalid_sort	400	sort is neither name nor updated.	List components
no_delivery_target_mapped	400	this environment publishes to no delivery environment.	Plan a publish, Publish content, Preview a stream
required_item_omitted	400	items the plan calls new are missing from items; the response names them.	Import a bundle
reserved_path	400	the resulting path is reserved and cannot be used by a page.	Update a node, Create a node
unknown_category	400	no category has this path or id.	Preview a stream
unknown_property	400	the body has a property this API does not recognize; the response names it in property.	Export a bundle, Plan an import, Import a bundle, Plan a publish, Publish content
unsupported_format_version	400	the bundle's formatVersion is not one this server accepts; the response gives supplied and supported.	Plan an import, Import a bundle
validation_failed	400	an unknown kind; the response lists the valid ones.	List the environment's items, Export a bundle, Plan an import, Import a bundle, Upload a blob, Find stored blobs by hash, Plan a publish, Publish content, Create a contract, Update a contract, Replace a folder's access rules, Replace a folder's allowed contracts, Create a component, Update a component, Create a template, Update a template, Create a site, Update a node, Create a node, Set a node's payload, Replace a node's access rules, Replace a node's allowed Templates, Resolve a draft preview, Create a category group, Rename a category group, Add a category group to the environment, Create a category, Update or move a category, Resolve a category path or id, Classify a component, Classify a page, Classify a contract, Create an adapter, Update an adapter, Preview an adapter, Create a stream, Replace a stream, Preview a stream
missing_api_key invalid_api_key	401	no key was sent, or it is unknown, revoked or expired.	Any operation
payment_required	402	the organization's subscription needs attention.	Any operation
quota_exceeded	402	the organization has reached its plan's category limit (platform.max_categories, counted across every app); quotaKey and limit say which.	Create a category
access_denied	403	the key's role cannot edit a folder or page node a selected item is in or would be filed under.	Import a bundle, Create a folder, Rename or move a folder, Delete a folder, Create a component, Update a component, Delete a component, Get a node, Update a node, Delete a node, List a node's children, Create a node, Move a node, Reorder sibling nodes, List what points at a node, Get where a node is used, Set a node's payload, Clear a node's payload, Resolve a draft preview, Classify a component, Classify a page
app_not_available	403	Content is not enabled for the organization.	Any operation
inherited_owner_not_permitted	403	the item is owned by a realm above the key's own (ownerRealmId). A person can edit it from the app and the change is written in the realm that owns it, but a key acts in one realm and never writes through to another: change it with a key bound to the owning realm.	Update a contract, Rename or move a folder, Update a component, Update a template, Update an adapter, Replace a stream
ip_denied	403	the caller's address is outside the key's allowed ranges.	Any operation
permission_denied	403	the bundle would contain a kind the key's role cannot manage; permission names the permission it lacks.	Export a bundle, Import a bundle, Create a contract, Update a contract, Delete a contract, Get a folder's access rules, Replace a folder's access rules, Get a folder's allowed contracts, Replace a folder's allowed contracts, Create a template, Update a template, Delete a template, Get a node's access rules, Replace a node's access rules, Get a node's allowed Templates, Replace a node's allowed Templates, Create a category group, Create a category group, Rename a category group, Delete a category group, Delete a category group, Add a category group to the environment, Remove a category group from the environment, Create a category, Update or move a category, Update or move a category, Delete a category, Classify a contract, Create an adapter, Update an adapter, Delete an adapter, Create a stream, Replace a stream, Delete a stream
quota_exceeded	403	the organization has reached its plan's component limit.	Create a component, Create a site, Create a node
scope_denied	403	the key lacks this route's scope.	Any operation
tier_required	403	the Content Management API needs the Pro plan or above.	Any operation
operation_not_found	404	no job with this id exists in the key's environment.	Get a job's status
unknown_choice_source	404	pluginKey is not a choice source activated for the organization.	Get a choice source's options
adapter_in_use	409	something still uses the adapter; usages lists each as { entityKind, entityId, name, fieldPath }, where entityKind is stream, adapter, component or node. Remove those uses first.	Delete an adapter
category_in_use	409	isSelectable: false was sent for a category that child categories, classification or field values still use; usages lists each usage as { sourceKind, sourceId, app, environmentId, environmentName, displayName }, gathered from every app that classifies with the vocabulary — app is content or assets, and environmentId/environmentName are set for a usage inside an environment.	Update or move a category, Delete a category
component_has_translation_jobs	409	a translation job for it is still in progress.	Delete a component
component_published	409	still published in the deliveryEnvironments listed; unpublish it first.	Delete a component
concurrency_conflict	409	the contract changed since rowVersion; the body carries currentRowVersion and currentUpdatedAtUtc, so re-read and reapply your change.	Update a contract, Update a component, Update a template, Update a node, Move a node, Rename a category group, Update or move a category, Update an adapter, Replace a stream
confirm_overwrite_required	409	items differ from the environment and were not confirmed; they are listed in items. Re-plan before confirming.	Import a bundle
contract_read_only	409	the contract is synced from a content provider and changes only when that provider is refreshed.	Update a contract, Delete a contract, Classify a contract
duplicate_external_id	409	another contract in this environment already has this external id.	Create a contract, Update a contract, Create a component, Create a template, Update a template, Create an adapter, Create a stream
duplicate_site_name	409	a site with this name already exists in the environment.	Create a site, Update a node
duplicate_slug	409	a sibling already resolves to this slug; localeSlot and conflictingNodeId say where.	Update a node, Create a node, Move a node
group_in_use	409	another environment or app still uses the group — a contract's category field names it, or an environment has added it; usages lists each usage as { sourceKind, sourceId, app, environmentId, environmentName, displayName }, gathered from every app that classifies with the vocabulary — app is content or assets, and environmentId/environmentName are set for a usage inside an environment.	Delete a category group, Remove a category group from the environment
group_not_empty	409	the group still has categories.	Delete a category group
has_dependents	409	other data depends on this contract. blockers groups the dependents' ids by reason: has_children, has_components (a count), referenced_by_folder_constraints, referenced_by_template_constraints, referenced_by_template_settings, referenced_by_adapter_constraints, referenced_by_streams, referenced_by_proposals and referenced_by_field_constraints.	Delete a contract, Delete a template, Delete a node
import_blocked	409	the plan has blockers, listed in blockers; nothing is written, including items that are not blocked.	Import a bundle
inherited_read_only	409	the contract is owned by a realm above the key's own.	Delete a contract, Rename or move a folder, Delete a folder, Update a component, Delete a component, Delete a template, Rename a category group, Delete a category group, Remove a category group from the environment, Create a category, Update or move a category, Delete a category, Classify a component, Classify a contract, Delete an adapter, Delete a stream
node_published	409	the node is live in the delivery environments deliveryEnvironments names; unpublish it there first.	Delete a node
not_empty	409	the folder contains child folders or components.	Delete a folder, Delete a node
referenced_by	409	still referenced; usages lists the components and pages that reference it and adapters the Adapters that look it up.	Delete a component
taxonomy_read_only	409	the group or category comes from a content provider and changes only when that provider is refreshed.	Rename a category group, Delete a category group, Create a category, Update or move a category, Delete a category
blob_too_large	413	the upload is over the size limit given in maxBytes.	Upload a blob
abstract_contract	422	that contract is abstract and cannot be instantiated.	Offer content for review
adapter_invalid	422	the adapter cannot be saved. errors lists each problem as { path, code, message }: invalid_rules (the rules are not well-formed), contract_not_found (the input or output contract does not exist), nested_adapter_not_found (a nested rule names an adapter that does not exist in this environment), and the type-compatibility and coverage problems /adapters/validate reports.	Create an adapter, Update an adapter, Validate an adapter
contract_not_found	422	the input or output contract (or that input contract version) does not exist.	Validate an adapter
invalid_rules	422	the rules are not well-formed.	Validate an adapter, Preview an adapter
proposal_workflow_not_assigned	422	no proposal workflow governs that folder, so there would be nobody to review this.	Offer content for review
stream_invalid	422	the definition cannot be saved. errors lists each problem as { target, code, message }, for example source_contracts_required, too_many_source_contracts, contract_not_found, adapter_not_found, stream_adapter_input_unsatisfied (a source contract does not satisfy the adapter's input contract), invalid_field_path, invalid_resolve_depth, too_many_exclusions, too_many_filters, duplicate_filter_key, unknown_filter_type, multiple_fulltext_filters and unknown_category_group.	Create a stream, Replace a stream
unknown_contract	422	no contract with that external id exists in this environment.	Offer content for review
unknown_folder	422	no folder at that path exists in this environment.	Offer content for review
workflow_state_not_editable	422	the component's workflow state (state, in definition) does not allow edits; move it to an editable state first.	Update a component, Update a node, Set a node's payload, Clear a node's payload
quota_exceeded	429	the organization's blob storage quota is full; the response gives the quota key and its limit. Rate limit or quota exceeded; Retry-After says how long to wait.	Upload a blob
too_many_failed_authentications	429	too many bad keys from this address.	Any operation
choice_source_failed	502	the source is unavailable or failed; message carries its own explanation. Check the source's configuration.	Get a choice source's options
bulk_operations_paused	503	background jobs are temporarily paused. Retry later.	Plan a publish, Publish content

Content Deployment API

Code	Status	Meaning	Returned by
not_a_promotion_target	400	the key's edge is no longer in the organization's topology.	Plan a promotion, Execute a promotion
promotion_root_required	400	the request has no root.	Execute a promotion
missing_api_key invalid_api_key	401	no key was sent, or it is unknown, revoked or expired.	Any operation
app_not_available	403	Content is not enabled for the organization.	Any operation
origin_denied ip_denied	403	a browser-safe key was used from an origin or address outside its restrictions.	Any operation
permission_denied	403	the role may not promote this item.	Execute a promotion
scope_denied	403	the key lacks this route's scope.	Describe the calling key, Plan a promotion, Plan a promotion, Execute a promotion, Execute a promotion
tier_required	403	the organization's plan is below Pro.	Plan a promotion
promotion_blocked_by_ancestor_realms	409	the promotion needs items owned by a realm above the key's own that the target lacks or has behind; they are listed as blockedByAncestorRealms. Nothing was written.	Execute a promotion
promotion_conflict	409	one or more diverged items were not both confirmed and allowed. The body lists them as items. Nothing was written.	Execute a promotion
promotion_blocked	422	the plan has blockers. They are listed as blockers.	Execute a promotion
too_many_failed_authentications	429	too many bad keys from this address.	Any operation

Audience Management API

Code	Status	Meaning	Returned by
individual_needs_name_or_identity	400	neither a name nor an identity was sent.	Create an individual
kind_not_accepted	400	page views are not accepted.	Record an interaction, Identify a person
unknown_fact	400	the stage has no such fact.	Open a stage for a person
validation_failed	400	a field is invalid; errors is keyed by field, and a custom field as attributes.<key>.	Create an individual, Update an individual, Add an identity, Set a channel permission, Record an interaction, Identify a person, Open a stage for a person, Create a task about a person, Resolve a review item, Create an audience, Change an audience, Create or update an account, Add a person to an account, Open a pass for an account
missing_api_key invalid_api_key	401	no key was sent, or it is unknown, revoked or expired, or it was not created from the Audience settings page.	Any operation
payment_required	402	the organization's subscription needs attention.	Any operation
app_not_available	403	Audience is not enabled for the organization.	Any operation
ip_denied	403	the caller's address is outside the key's allowed ranges.	Any operation
quota_exceeded	403	the plan's individual limit (audience.max_individuals) is reached; quotaKey names it. Nothing is created and everyone already held stays as they are.	Create an individual, Identify a person, Create or update an account
scope_denied	403	the key lacks this route's scope.	Any operation
transition_not_allowed	403	the transition has a role allow-list, and a key holds no role.	Move a pass to another state, Move an account's pass
account_not_found	404	no account with that external id in this organization.	Get an account, Delete an account, Remove a person from an account, Get an account's lifecycle
audience_not_found	404	no such audience in this organization.	Get an audience
individual_not_found	404	no such person in this organization.	Get an individual, Update an individual, Add an identity, Set a channel permission, List a person's interactions, Record an interaction, Forget a person, List a person's lifecycle stages
individual_not_found identity_not_found	404	no such person or identity.	Remove an identity
not_found	404	no such route.	Any operation
stage_row_not_found	404	no such pass for this person.	Change a pass's facts
accounts_not_enabled	409	account was sent but the organization has not turned accounts on; nothing was written.	Identify a person, List accounts, Get an account, Create or update an account, Delete an account, Add a person to an account, Remove a person from an account, Get an account's lifecycle
audience_limit_reached	409	the organization already holds 200 audiences.	Create an audience
concurrency_conflict	409	the person changed since rowVersion was read.	Update an individual, Change a pass's facts, Change an audience
identity_verified_elsewhere	409	a verified identity is already held by another person; holder names them.	Create an individual, Add an identity
individual_merged	409	the person was merged into another; use the survivor.	Open a stage for a person, Create a task about a person
invalid_transition	409	that transition does not leave the pass's current state.	Move a pass to another state
outcome_blocked	409	a closing action failed and the pass was left where it was. stage_row_closed.	Move a pass to another state
review_item_closed	409	the item is not open.	Dismiss a review item
stage_already_open	409	the person already has an open pass in this stage.	Open a stage for a person, Open a pass for an account
stage_row_closed	409	a closed pass is a record and is not edited.	Change a pass's facts
survivor_not_in_pair	409	survivorId is not one of the two people. concurrency_conflict.	Resolve a review item
transition_vetoed	409	the transition's condition is not met.	Move a pass to another state
rate_limited	429	the key spent its requests-per-minute budget; Retry-After says how long to wait.	Any operation
too_many_failed_authentications	429	too many bad keys from this address.	Any operation

Forms SDK API

Code	Status	Meaning	Returned by
missing_api_key invalid_api_key	401	no key was sent, or it is unknown, revoked or expired.	Any operation
payment_required	402	the organization's subscription needs attention.	Any operation
ip_denied	403	the caller's address is outside the key's allowed ranges.	Any operation
scope_denied	403	the key lacks forms.sdk.forms.read.	Any operation
submission_key_clash	409	two fields share a submission key. clashingKeys names them; fix it in the Forms editor.	Get a form
too_many_failed_authentications	429	too many bad keys from this address.	Any operation