Sorry, no results found for "".
When an API endpoint fails for any reason, it will return an HTTP status code outside the 2xx range.
The response body will include an array of api_error entities that provide detailed information about the issue. Each error entity contains the following attributes:
code: A unique identifier for the specific error.
doc_url: A link to this documentation page for additional context.
details: Additional information describing the cause of the error.
transient (optional): If set to true, this indicates the error is temporary. You can retry the request later as the issue may resolve itself.
As an example, this could be the response for a request that tries to create a new model, but the provided api_key is already used by another model:
{ "data": [ { "id": "ce9dcb", "type": "api_error", "attributes": { "code": "INVALID_FIELD", "doc_url": "https://www.datocms.com/docs/content-management-api/errors#INVALID_FIELD", "details": { "field": "api_key", "code": "VALIDATION_UNIQUENESS", "record_type": "ItemType" } } } ]}ACCOUNT_ALREADY_JOINED_SITE This error occurs when an attempt is made to invite a collaborator with an email that is already a member of the specified DatoCMS project. Ensure that the email provided for the user you are trying to invite is not already associated with an existing user in the project, or with the owner of the project itself.
ALREADY_PRIMARY_ENVIRONMENT This error occurs when an attempt is made to promote an environment that is already set as the primary. Ensure that the environment you are trying to promote differs from the existing primary.
CANNOT_CREATE_OR_DESTROY_SCHEMA_MENU_ITEM_LINKED_TO_ITEM_TYPE This error occurs when attempting to create or delete schema menu items that are linked to a specific model. Such entities are read-only and are automatically managed by DatoCMS. Only schema menu items not linked to an model can be created/modified/deleted.
CANNOT_DESTROY_CURRENT_USER This error occurs when an API token attempts to delete itself. To resolve this issue, ensure that the request is made by a different access token than the one intended for deletion.
CANNOT_DESTROY_FORKING_ORIGIN This error occurs when attempting to delete an environment that is currently serving as an origin for another environment that is still being created. To resolve this, ensure that no existing environment is being forked from the one you wish to delete, or wait for the creation processes to complete before retrying the deletion request.
CANNOT_DESTROY_PRIMARY_ENVIRONMENT This error occurs when an attempt is made to delete the primary environment of a DatoCMS project. The primary environment serves as the main staging area for content, and deletion is not permitted to maintain data integrity. To resolve this, ensure you're targeting a non-primary environment for deletion.
CANNOT_UPGRADE_MODERN_PLUGIN_INTO_LEGACY This error occurs when attempting to update an existing modern plugin by setting properties that only make sense for legacy DatoCMS plugins (i.e., plugin_type). While it's possible to convert a legacy plugin into a modern one, the opposite is not possible.
CLASHING_FIELD_LABELS This error occurs when attempting to delete a fieldset, and the fieldset includes a field that carries a label already used by another field at the root level. To resolve this, make sure that all field labels within the fieldset are distinct.
CONCURRENT_ENVIRONMENT_UPDATE This error happens when you try to modify an environment while another operation is also updating the same environment. To resolve this issue, ensure that no other requests are modifying the targeted environment at the same time, or implement logic to retry the request after a delay.
CONCURRENT_ITEM_TYPE_UPDATE This error occurs when you try to modify a model or any entity connected to it while validation is in progress. To resolve this, please wait for the current validation to complete before trying your request again.
CONCURRENT_ITEM_UPDATE This error occurs when an attempt is made to modify a record that is concurrently being updated by another API request. This typically happens when two API requests try to change the same record at the same time. To resolve this, ensure that you implement retry logic in your application, allowing it to gracefully handle such conflicts by retrying the request after a brief wait.
CONCURRENT_ROLE_UPDATE This error occurs when an attempt is made to modify a role that is concurrently being updated by another API request. This typically happens when two API requests try to change the same role at the same time. To resolve this, ensure you implement retry logic in your application, allowing it to gracefully handle such conflicts by retrying the request after a brief wait.
CONCURRENT_UPLOAD_UPDATE This error occurs when an attempt is made to modify an upload that is concurrently being updated by another API request. This typically happens when two API requests try to change the same content upload at the same time. To resolve this, ensure that you implement retry logic in your application, allowing it to gracefully handle such conflicts by retrying the request after a brief wait.
DEACTIVATED_SITE This error happens when an API request tries to change content on a deactivated project. A deactivated project doesn't allow content modifications. To fix this, go to the DatoCMS dashboard and address any pending billing issues.
DELETE_RESTRICTION This error occurs when an API request attempts to delete a resource, but there's a restriction or constraint that prevents the deletion from happening. Ensure that the content you are trying to delete is not being referenced or constrained by other linked entities. This error is not related to missing user permissions. Check your request for dependencies and remove or update those references before retrying the deletion.
DESTINATION_USER_REQUIRED This error happens when you try to delete a collaborator or API token that created resources (records/uploads). Make sure the API request specifies a valid destination that will take ownership; otherwise, the operation cannot be completed.
DUPLICATE_POSITIONS_FOUND This error happens when an API request breaks position rules in a tree-like structure — i.e., fields/fieldsets/menu items/upload collections — often during reordering. To fix this, make sure all positions for entities are unique within their parent context to avoid duplicates. Check your payload before sending the request to prevent conflicts.
DUPLICATE_SINGLETON This error happens when trying to create a record for a "Single instance" model, but a record of that type already exists in the project. If the model is set as "single instance", check that no other instance exists before performing the request.
ENVIRONMENT_IN_READ_ONLY_MODE This error occurs when an attempt to modify content is made while the environment is temporarily in read-only mode due to pending operations (such as an environment fast-fork). To resolve it, ensure that the environment is in a writable state before executing any modification requests.
ENVIRONMENT_NOT_READY This error occurs when a modification request is made to an environment that is not in a "ready" state. To resolve this, ensure that the environment you’re targeting has transitioned to "ready" status. You can check the current environment's status via the DatoCMS interface or API before making modification requests.
EXCEPTION This error occurs when DatoCMS encounters an unhandled exception. Should you encounter this error, we kindly ask that you contact our support team.
IMMUTABLE_UPLOAD_TRACKS_IN_SANDBOX_ENVIRONMENT This error occurs when attempting to modify upload tracks in a non-primary environment. Specifically, it's triggered if the API token's associated account is using a sandbox environment rather than a production environment, which restricts such modifications. To resolve this, ensure that your requests to create or destroy tracks are made in the primary environment.
INCOMPATIBLE_WITH_UPLOAD_STORAGE_SETTINGS This error occurs when trying to alter the Asset CDN settings for a project that uses Enterprise-level, custom upload storage configurations. If you have custom upload storage, you must manage these settings within your architecture.
INSUFFICIENT_PERMISSIONS This error occurs when the current API token lacks sufficient permissions to perform the requested action. To resolve this, ensure that the API token being used has the necessary permissions for the attempted operation.
INVALID_ACCEPT_HEADER This error happens when the API request to modify content doesn't have a valid "Accept" header (application/json, application/vnd.api+json). Make sure your request includes an "Accept" header that matches the media types required by the API.
INVALID_API_VERSION This error occurs when the X-Api-Version header in your request does not match any supported API version for the current DatoCMS project. Ensure that your API requests specify a valid version (e.g., 1, 2, or 3).
INVALID_ATTRIBUTES This error occurs when a request to modify content includes attributes that do not match the expected schema for the specified model. Ensure that only valid fields defined in your DatoCMS model are included in the request payload, and double-check for any typos or extraneous data that may have been added inadvertently.
INVALID_AUTHORIZATION_HEADER This error occurs when the provided API Authorization header is invalid or absent during requests to modify content. Ensure that the API token used in the request is valid and properly formatted.
INVALID_CONTENT_TYPE_HEADER This error occurs when a request to modify content is made without a valid Content-Type header. Specifically, it is triggered if the header does not indicate a JSON format, which is required for POST, PUT, or PATCH requests. To resolve this, ensure that your requests contain the Content-Type header with application/json or application/vnd.api+json.
INVALID_DATE This error occurs when the API receives a date value that does not conform to the expected format, potentially due to an incorrect timezone or an invalid date string. To resolve it, ensure that date values are in ISO 8601 format.
INVALID_DESTINATION_TYPE This error happens when an API request includes an unrecognized ownership type. To fix this, make sure the specified type is either user, account, organization, sso_user, or access_token.
INVALID_DESTINATION_USER This error occurs when you attempt to delete a collaborator or API token while designating an invalid destination for ownership transfer (specifically, the user being deleted). Ensure that the API request indicates a valid destination for ownership; otherwise, the operation cannot be finalized.
INVALID_DRAFT This error occurs when an API request attempts to publish a draft that fails validation checks. To resolve this issue, ensure that the record meets the content model's validation criteria before attempting the operation.
INVALID_ENDPOINT This error occurs when an API request is made to an endpoint that does not exist or is not accessible by the current user. Check the URL for typos and confirm that the endpoint is valid for the intended resource type and user permissions to ensure proper access when modifying content.
INVALID_ENTITY_ID This error occurs when an API request attempts to pass an invalid or improperly formatted ID. Specifically, the entity ID must be a Version 4 UUID formatted in URL-safe base64. Ensure that the ID provided in the request adheres to these specifications to resolve the issue.
INVALID_ENVIRONMENT This error occurs when an API request attempts to access or modify content within an environment that does not exist or is not accessible by the current API token. Verify that the desired environment is accessible, activated, and ready. Check your authentication and environment identifiers in the request.
INVALID_FIELD This error occurs when an API request to alter content fails validation, typically due to inconsistencies or absent fields in the payload. Please examine the specifics of the error you received to identify which field is causing the problem.
INVALID_FILTER_FIELDS_PARAM This error occurs when the API receives invalid filtering parameters. Common triggers include using incorrect field names, unsupported operators, or failing to provide necessary conditions in your query. To resolve the issue, ensure that your filter parameters conform to the expected query structure, including valid field names and proper formatting.
INVALID_FORMAT This error occurs when the payload of an API request to alter content (POST, PUT, DELETE) fails validation, typically due to an invalid format or absent fields in the payload. To resolve this, please examine the specifics of the error you received to identify which part of the payload is causing the problem.
INVALID_JSON_BODY This error occurs when the API receives a request containing malformed JSON data. Common triggers include incorrect syntax, missing braces, or non-JSON compliant data types in the request body. Ensure that your JSON is correctly formatted to resolve this issue.
INVALID_ORDERING This error occurs when the combination of ordering parameters provided in your API request is invalid. Common triggers include specifying both a meta ordering and a field ordering simultaneously, or attempting to set an ordering on "single instance" models. Review your request to ensure that the ordering parameters are correctly configured.
INVALID_ORDERING_FOR_SINGLETON_ITEM_TYPE This error occurs when attempting to set an ordering field on a single instance model. Single instance models do not support custom ordering. To resolve this issue, ensure that the model is not marked as a single instance before attempting to modify ordering fields.
INVALID_ORDERING_FOR_SORTABLE_ITEM_TYPE This error occurs when an attempt is made to set an ordering field for a model designated as sortable or tree-like. To resolve this, ensure that the model’s attributes do not include the sortable or tree flags before modifying the ordering. Check the model's configuration and adjust accordingly.
INVALID_PARAMS This error occurs when the API request includes query string parameters that do not meet the required validation criteria. Review your request for completeness and compliance with the expected structure, and ensure that it adheres to all relevant constraints.
INVALID_PARENT This error occurs when a request attempts to modify an entity by assigning a parent that creates a circular relationship or exceeds the allowable hierarchy depth. Ensure that the parent entity being assigned is not already a child in the current modification path, and that the nesting limit is respected.
INVALID_PARENT_ID This error occurs when a request attempts to assign an invalid or nonexistent parent in a record under a tree-like collection. Ensure that the specified parent ID is a valid string referencing an existing record within the project and that it is not identical to the record's own ID, as this creates a circular reference.
INVALID_PLUGIN_VERSION This error occurs when an API request attempts to update a plugin to a version that is either incorrect or does not exist in the npm registry, typically due to an invalid or malformed version string. Ensure that the given package version is valid and corresponds with available plugin versions in the npm registry to resolve this issue.
INVALID_POSITION This error occurs when the API request includes an invalid type for the position attribute during a record modification, particularly for sortable or tree-structured models. To resolve it, ensure that the position field is an integer and meets the required conditions for the target model in your DatoCMS project.
INVALID_RELATIONSHIP This error occurs when a requested operation violates relationship constraints between entities in DatoCMS. Specifically, it may be triggered if you attempt to associate incorrect entities in a relationship. To resolve this, ensure that relationships between your entities are correctly defined and compatible.
INVALID_REQUEST This generic error occurs when an API request fails validation due to mismatched required properties in the request payload.
INVALID_SITE This error only occurs when an authentication method different from the API token is used in the request and signals that it's not possible to trace the request back to a particular DatoCMS project. This error should not happen if you're using API tokens as the authentication method.
INVALID_SITE_EXPORT_SETTINGS This error occurs in the context of offline backups, a DatoCMS Enterprise feature. Common triggers include improper values in the backup settings or an invalid adapter type. To resolve this, ensure that all required fields are correctly populated and conform to the expected types.
INVALID_TYPE This error occurs when attempting to create or update content using an model identifier that doesn't exist within your project's schema. To resolve, verify that the item_type relationship in your API request matches a valid model ID from your project's content model.
INVALID_UPLOAD_STORAGE_SETTINGS This error occurs in the context of custom uploads storage (S3, GCP, etc.), a DatoCMS Enterprise feature. Common triggers include improper values in the custom uploads storage settings or an invalid adapter type. To resolve this, ensure that all required fields are correctly populated and conform to the expected types.
ITEM_LOCKED This error occurs when attempting to modify a record that is currently locked for editing by another user. It typically arises if a different session holds a lock on the record, preventing concurrent modifications. To resolve this, ensure that the record is unlocked or wait for the user holding the lock to complete their changes before retrying the API request.
ITEM_TYPE_CANNOT_BE_CHANGED This error occurs when an attempt is made to change the type of an existing record in DatoCMS. Typically, this validation error arises during an update operation where the model specified in the request does not match the current model stored in the system. To resolve this, ensure that the model remains consistent with the defined schema during updates.
ITEM_TYPE_IS_SINGLETON This error occurs when attempting to modify or duplicate a record of a type designated as "single instance," which means only one record of that model is allowed. To resolve this, ensure you're not trying to create a second record for a model that is defined as "single instance" within your DatoCMS project.
ITEM_TYPE_NOT_FOUND This error occurs when the specified model in your API request does not match any existing models within the current project. Check that the model ID or API key is correct and that the current user has access to the associated project.
KIND_CANNOT_BE_CHANGED This error occurs when an attempt is made to modify the "kind" of an existing schema menu item within DatoCMS. This validation ensures that the record retains its original structure, which is crucial for maintaining data integrity across the content management system. To resolve this, ensure that the "kind" attribute is not modified in your API request.
MAINTENANCE_MODE This error occurs when the current site's primary environment is under maintenance, preventing any modification requests. To resolve this issue, confirm that maintenance mode is disabled for the project or coordinate with platform admins to schedule necessary updates outside maintenance periods.
MISSING_BUILD_TRIGGER_ID_PARAMETER This error occurs when a Site Search does not include the required filter[build_trigger_id] query string parameter. To resolve this, ensure that the client request includes this parameter with a valid value.
MISSING_FIELDS This error occurs when a request to create a record lacks some required fields. To resolve this, inspect the details of the error to understand which fields are missing, and ensure that your API request includes all mandatory fields.
MISSING_LOCALES This error occurs when a request to create a record containing localized fields does not specify a value for any locale at all. To resolve this, ensure that you provide at least one value for one of the environment locales for each of the localized fields of the model.
MISSING_QUERY_PARAMETER This error occurs when a Site Search does not include the required filter[query] query string parameter with the actual search term. To resolve this, ensure that the client request includes this parameter with a valid value.
MISSING_UPLOAD_IDS This error occurs when a batch API request to update uploads lacks the required filter[ids] query string parameter, which specifies the IDs of the uploads to be modified. Ensure that your request includes this parameter with either a valid array of upload IDs or a comma-separated list of IDs to resolve the issue.
MODULAR_BLOCK_IN_USE This error occurs when an attempt is made to delete a block model that is currently in use by one or more structured text or modular content fields within the environment. To resolve this, ensure that the block is not referenced by any field before executing deletions.
MUX_ERROR This error occurs when an operation regarding video uploads is attempted through the API, but Mux is unable to process it. To resolve this issue, please inspect the details of the error message provided for more specific information about what went wrong.
NEW_PLUGIN_VERSION_IS_INCOMPATIBLE This error occurs when a request attempts to upgrade a legacy plugin with different settings for either the plugin type, field types in which it can operate, or the settings that the plugin offers. Review your API request payload for discrepancies to resolve the issue.
NON_EDITABLE_ACCESS_TOKEN This error occurs when attempting to modify or delete a non-editable API token for the project — either the Full-access API token or the Read-only API token. To resolve this, ensure that you are not trying to modify or delete such tokens.
NOT_A_VIDEO This error occurs when an API request attempts to add a track — either an additional audio track or a subtitle — to an upload that is not classified as a video. Ensure that the upload you're working with is a valid video file to resolve this issue.
NOT_FOUND This error occurs when an API request attempts to access a resource that is not present in the system. Common triggers for this issue include specifying an invalid ID in your request. To resolve this, verify the entity ID and ensure that the API token has the necessary permissions to access it.
NOT_ON_PER_SITE_PRICING This error occurs when attempting to read entities that are only available in a DatoCMS project under the legacy per-project pricing. To resolve it, ensure that the current account or organization that owns the project has subscribed to a per-project pricing plan.
NO_PRIMARY_AUDIO_TRACK This error occurs when an attempt is made to generate automatic subtitles on uploads that lack a designated primary audio track. To resolve the issue, ensure that the upload associated with your request includes a valid primary audio track before proceeding with the operation.
PLAN_UPGRADE_REQUIRED This error occurs when a request attempts to exceed the limits defined by the current subscription plan for workflows, upload sizes, or similar features. To resolve this, review your account's plan details and consider upgrading if you need access to additional resources or functionality.
PLATFORM_SCHEDULED_MAINTENANCE This error arises when an API request is submitted during scheduled maintenance. During such maintenance, all DatoCMS projects become read-only. To address this issue, please check the status of the scheduled maintenance at https://status.datocms.com
PRIMARY_ENVIRONMENT_SETTINGS_READ_ONLY This error occurs if the "Force the use of sandbox environments" setting is activated for a DatoCMS project and an attempt is made to change the primary environment settings – including changes to its content schema and role permission rules regarding the environment. To resolve this issue, either disable the "Force the use of sandbox environments" flag or ensure that your API request targets a sandbox environment.
PUBLISHED_CHILDREN This error occurs when attempting to unpublish a record in a tree-structured collection that has one or more published child records. To resolve it, either ensure that all published children are unpublished before performing the unpublish action on the parent record, or pass the recursive=true query string parameter to the request.
PUBLISHED_REFERENCES This error occurs when attempting to unpublish a record that is currently referenced by one or more published records. To resolve it, either change the on_reference_unpublish_strategy of the fields that are referencing the record to delete_references or unpublish, manually remove the references from the published records, or manually unpublish the records that reference this record as well. You can inspect the error message for more details on which specific records are causing the issue.
RATE_LIMIT_EXCEEDED This error occurs when making a request to the API, but the number of requests exceeds the allowed limit within a specified time frame. To resolve the issue, ensure that your application throttles requests, waiting for the X-RateLimit-Reset period before retrying. Monitor your request volume and optimize where necessary to avoid triggering this limit.
REQUIRED_BY_ASSOCIATION This error occurs when you attempt to delete a record that is currently referenced by another record. To resolve this, either change the on_reference_delete_strategy of the fields that are referencing the record to delete_references, or ensure that no record relies on this record before deleting it, and consider removing those references first.
SERVICE_UNAVAILABLE This error occurs when our servers are temporarily unable to handle your request. This could be due to planned or unplanned maintenance, a system upgrade, or a server failure. These errors can also be returned during periods of high traffic. We suggest monitoring the API status at https://status.datocms.com for ongoing issues that may affect service availability.
SITE_NOT_READY This error occurs when an API request attempts to access or modify content within a project that is not yet accessible, as it's still being finalized. Verify that the desired project is accessible, activated, and ready.
SSO_SETTINGS_REQUIRED This error occurs in the context of the Single-Sign On enterprise feature of DatoCMS, specifically when the API attempts to perform some operation but the SSO settings have not yet been configured. Ensure that Single Sign-On is enabled and its settings are properly set for the current project before making this request.
STALE_ITEM_VERSION This error occurs when an attempt is made to update a record that has already been modified since it was last read. To resolve the issue, ensure that you're working with the latest record version by re-fetching the record before making updates, and verify that the current version matches the expected value in your request payload.
TECHNICAL_LIMIT_REACHED This error occurs when you attempt to create new entities in your DatoCMS project but have exceeded allowed limits based on your current API token's subscription plan. It may happen if the content's byte size is too large, the number of blocks within a record exceeds the maximum, or if blocks are nested beyond permitted levels. To resolve it, inspect the error and find which limit is triggering the error, then check your subscription's limits and adjust your API request accordingly.
TOO_MANY_OPERATIONS This error occurs when an API request exceeds the maximum allowed number of batch operations. To resolve it, ensure that the number of operations in your batch does not exceed the limit of 200.
UNMANAGED_EDIT_CONFLICT This error typically arises when the current API token attempts to lock a record for editing, but another user has already locked it. To solve this issue, wait a few minutes and retry your request.
UNPUBLISHED_LINK This error occurs when an attempt is made to publish a record that references other unpublished records. To resolve it, either change the on_publish_with_unpublished_references_strategy of the fields that are referencing the record to publish_references, manually remove the references from the record, or manually publish the referenced records as well. You can inspect the error message for more details on which specific records are causing the issue.
UNPUBLISHED_PARENT This error occurs when attempting to publish a record that has one or more parent records that are not yet published. Ensure that all parent records are successfully published before trying to publish the intended record. Check the details of the error and record's hierarchy to find the records that need to be published first.
UPLOAD_IS_CURRENTLY_IN_USE This error occurs when you attempt to delete an upload that is currently in use by one or more records in your DatoCMS project. To resolve this, first check which records are referencing the upload by looking at the error details. Ensure that all references are removed before re-attempting the deletion.
UPLOAD_NOT_PASSING_FIELD_VALIDATIONS This error occurs when an upload is currently referenced by one or more records, and the change requested to the upload fails to meet the field validations in place for those records. To resolve this issue, you should review the validation rules for your content model.
USED_AS_SLUG_SOURCE This error occurs when attempting to modify a field that a slug field depends on. To resolve it, identify the related slug in the details of the error, and either remove it or adjust its requirement before making the desired changes to the field.