# Error codes & handling failures (CMA)

### Content Management API Errors

CMA errors happen when your automation script, backend, or (rarely) frontend experiences a failure while talking to our REST Content Management API. This can happen for a variety of reasons, detailed below.

> [!NOTE] These errors are only for the REST Content Management API
> If you're looking for errors related to our GraphQL Content Delivery API, please instead see: [Error codes & handling failures (CDA)](https://www.datocms.com/docs/content-delivery-api/errors.md)

## Non-200 HTTP Status Codes

When an Content Management API endpoint **fails for any reason,** it will return an **HTTP status code outside the** `**2xx**` **range**.

Parse its JSON response body and use the detailed error codes below to troubleshoot.

## CMA Error JSON Body Response Structure

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](https://www.datocms.com/docs/content-management-api/resources/item-type/create.md), but the provided `api_key` is already used by another model:

```json
{
  "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"
        }
      }
    }
  ]
}
```

## Error codes

###### `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.

###### `BILLING_PROFILE_DEFAULTING`

This error occurs when attempting to perform an operation on a billing profile that has been cancelled. Ensure the billing profile is in an active state before retrying the request.

###### `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.

###### `DESTRUCTIVE_REQUEST_BLOCKED`

This error occurs when a write request (anything other than `GET` or `HEAD`) is sent with the `X-Abort-If-Destructive-Request` header — typically by DatoCMS's official MCP server in read-only mode. To resolve it, use the unsafe script execution tools instead of the safe ones.

###### `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_SEARCH_INDEX_ID`

This error occurs when attempting to search using a `filter[search_index_id]` parameter with a value that does not correspond to any existing search index in your project. The search index ID you provided is either incorrect, the search index may have been deleted, or it is disabled. Please verify that you are using a valid and enabled search index ID from your project's search indexes list.

###### `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.

###### `KEEP_URL_CONTENT_TYPE_CONFLICT`

This error occurs when attempting to replace an asset with the `keep_url` strategy using a file that has a different MIME type (Content-Type). Even if the file extensions match, the underlying content type must be identical to avoid Content-Type header inconsistencies and ensure proper browser handling.

To resolve this error, either:

-   Use the `create_new_url` strategy to generate a new URL for the new content type

-   Ensure the replacement file has the exact same MIME type as the original file

###### `KEEP_URL_FORMAT_CONFLICT`

This error occurs when attempting to replace an asset with the `keep_url` strategy using a file that has a different format/extension. You cannot replace a `.png` file with a `.jpg` file while keeping the same URL, as this would make the URL misleading about the actual file format and could cause browser compatibility and caching issues.

To resolve this error, either:

-   Use the `create_new_url` strategy to generate a new URL with the correct extension

-   Ensure the replacement file has the same format/extension as the original file

###### `KEEP_URL_STORAGE_NOT_SUPPORTED`

This error occurs when attempting to replace an asset with the `keep_url` strategy while using custom upload storage settings. The `keep_url` strategy is only supported when using DatoCMS's default storage configuration.

To resolve this error, either:

-   Use the `create_new_url` strategy to generate a new URL for the replaced asset

-   Switch to DatoCMS's default storage settings if you need to use the `keep_url` strategy

###### `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_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.

###### `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](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](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.

###### `UNRESOLVABLE_SEARCH_INDEX`

This error occurs when attempting to search but no valid search index could be found. Either provide a valid `filter[search_index_id]` parameter to specify which search index to use, or ensure that at least one enabled search index exists in your project.

###### `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.

###### `USE_SEARCH_INDEX_ID_INSTEAD_OF_BUILD_TRIGGER_ID`

This error occurs when attempting to search using `filter[build_trigger_id]` parameter on a build trigger that has multiple search indexes associated with it. Since the `build_trigger_id` parameter is ambiguous in this case, you must use the `filter[search_index_id]` parameter instead to explicitly specify which search index to query.

## Related content in "Content Management API"

- [Content Management API Overview](https://www.datocms.com/docs/content-management-api.md)

- [Using the JavaScript CMA client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients.md)
- [API versioning](https://www.datocms.com/docs/content-management-api/api-versioning.md)

- [Authentication](https://www.datocms.com/docs/content-management-api/authentication.md)
- [Environments](https://www.datocms.com/docs/content-management-api/setting-the-environment.md)

- [Error codes & handling failures (CMA)](https://www.datocms.com/docs/content-management-api/errors.md)
- [Pagination](https://www.datocms.com/docs/content-management-api/pagination.md)

- [Asynchronous jobs](https://www.datocms.com/docs/content-management-api/async-jobs.md)
- [Technical Limits (CMA)](https://www.datocms.com/docs/content-management-api/technical-limits.md)

- [Record](https://www.datocms.com/docs/content-management-api/resources/item.md)
- [Scheduled publication](https://www.datocms.com/docs/content-management-api/resources/scheduled-publication.md)

- [Scheduled unpublishing](https://www.datocms.com/docs/content-management-api/resources/scheduled-unpublishing.md)
- [Upload](https://www.datocms.com/docs/content-management-api/resources/upload.md)

- [Site](https://www.datocms.com/docs/content-management-api/resources/site.md)
- [Model/Block model](https://www.datocms.com/docs/content-management-api/resources/item-type.md)

- [Field](https://www.datocms.com/docs/content-management-api/resources/field.md)
- [Fieldset](https://www.datocms.com/docs/content-management-api/resources/fieldset.md)

- [Record version](https://www.datocms.com/docs/content-management-api/resources/item-version.md)
- [Upload permission](https://www.datocms.com/docs/content-management-api/resources/upload-request.md)

- [Upload track](https://www.datocms.com/docs/content-management-api/resources/upload-track.md)
- [Manual tags](https://www.datocms.com/docs/content-management-api/resources/upload-tag.md)

- [Smart tags](https://www.datocms.com/docs/content-management-api/resources/upload-smart-tag.md)
- [Upload Collection](https://www.datocms.com/docs/content-management-api/resources/upload-collection.md)

- [Search Index](https://www.datocms.com/docs/content-management-api/resources/search-index.md)
- [Search result](https://www.datocms.com/docs/content-management-api/resources/search-result.md)

- [Search indexing activity](https://www.datocms.com/docs/content-management-api/resources/search-index-event.md)
- [Environment](https://www.datocms.com/docs/content-management-api/resources/environment.md)

- [Maintenance mode](https://www.datocms.com/docs/content-management-api/resources/maintenance-mode.md)
- [Menu Item](https://www.datocms.com/docs/content-management-api/resources/menu-item.md)

- [Schema Menu Item](https://www.datocms.com/docs/content-management-api/resources/schema-menu-item.md)
- [Uploads filter](https://www.datocms.com/docs/content-management-api/resources/upload-filter.md)

- [Model filter](https://www.datocms.com/docs/content-management-api/resources/item-type-filter.md)
- [Plugin](https://www.datocms.com/docs/content-management-api/resources/plugin.md)

- [Workflow](https://www.datocms.com/docs/content-management-api/resources/workflow.md)
- [Asynchronous job](https://www.datocms.com/docs/content-management-api/resources/job.md)

- [Job result](https://www.datocms.com/docs/content-management-api/resources/job-result.md)
- [Account](https://www.datocms.com/docs/content-management-api/resources/account.md)

- [Organization](https://www.datocms.com/docs/content-management-api/resources/organization.md)
- [Invitation](https://www.datocms.com/docs/content-management-api/resources/site-invitation.md)

- [Collaborator](https://www.datocms.com/docs/content-management-api/resources/user.md)
- [Role](https://www.datocms.com/docs/content-management-api/resources/role.md)

- [API token](https://www.datocms.com/docs/content-management-api/resources/access-token.md)
- [Webhook](https://www.datocms.com/docs/content-management-api/resources/webhook.md)

- [Webhook call](https://www.datocms.com/docs/content-management-api/resources/webhook-call.md)
- [Build trigger](https://www.datocms.com/docs/content-management-api/resources/build-trigger.md)

- [Deploy activity](https://www.datocms.com/docs/content-management-api/resources/build-event.md)
- [Subscription limit](https://www.datocms.com/docs/content-management-api/resources/subscription-limit.md)

- [Subscription feature](https://www.datocms.com/docs/content-management-api/resources/subscription-feature.md)
- [SSO Settings](https://www.datocms.com/docs/content-management-api/resources/sso-settings.md)

- [SSO User](https://www.datocms.com/docs/content-management-api/resources/sso-user.md)
- [SSO Group](https://www.datocms.com/docs/content-management-api/resources/sso-group.md)

- [White-label settings](https://www.datocms.com/docs/content-management-api/resources/white-label-settings.md)
- [Audit log event](https://www.datocms.com/docs/content-management-api/resources/audit-log-event.md)