> This page is for Unified. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Writes warnings and errors reference > Reference table of warning and error codes returned by POST endpoints, with causes and resolution steps. --- ## Warning and error codes This is a reference list of all possible errors and warnings returned by Merge's API's POST endpoints. > **Info** > > For more information on errors and warnings related to POST requests to Merge, check out the guide on [Troubleshooting Writes](/merge-unified/writing-data/troubleshooting-writes/troubleshooting-tools). | Issue | Type | Description | Troubleshooting Tips | | ------------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CORRUPTED_FILE` | Error | The file was corrupted, thus Merge was unable to get the contents. | Check that the file passed in the request is readable. | | `CREDENTIAL_REFRESH_FAILED` | Error | Credential refresh for linked account failed when attempting to make API request. | Navigate to [https://app.merge.dev/logs](https://app.merge.dev/logs) view the logs for the linked account to get more information. | | `DISABLED_MODEL_WRITE` | Error | A write request to a disabled model was attempted. | Navigate to [https://app.merge.dev/organization/common-models](https://app.merge.dev/organization/common-models) to re-enable the model. | | `DUPLICATE_MODEL_EXISTS` | Error | A model with duplicate unique identifiers already exists. | If testing, ensure that none test data is used in subsequent requests. | | `ERROR` | Error | A generic error type used for errors not enumerated in this list. | Use Debug Mode to get the relevant logs for troubleshooting. | | `INCORRECT_FIELD_TYPE` | Error | The field's value was in the incorrect format and Merge was unable to convert it, resulting in the Common Model not being created. | Ensure that the value being passed into the specified source field is in the correct data type. | | `INCORRECT_FIELD_TYPE` | Warning | The field's value was in the incorrect format, but Merge was able to convert it and create the Common Model instance. | Ensure that the value being passed into the specified source field is in the correct data type and no data is being accidentally altered when Merge casts the value. | | `INVALID_FIELD_CHOICE` | Error | The field value does not match an available enum choice for the field. | Consult the available field value choices for the relevant field in the API documentation. | | `INVALID_FILE_URL` | Error | The file associated with the URL passed in failed to download. | Make sure that the file URL of url passed in is accurate. | | `INVALID_REQUEST_CONTENT_TYPE` | Error | The content type for the body of the request was not correct. | Ensure that the value for content_type in your request headers is application/json. | | `INVALID_REQUEST_DATA_SHAPE` | Error | The request body does not match the expected request shape for the endpoint. | Ensure that the request body is in the correct format. | | `MISSING_PERMISSION` | Error | The user associated with the linked account does not have permission to perform this operation. | Ensure the account token is being passed into the request. Check [https://app.merge.dev/logs](https://app.merge.dev/logs) for more information. | | `MISSING_REQUIRED_FIELD` | Error | This request is missing fields required to add / update the Common Model in the given third-party platform. | Ensure the request body includes all required fields for creating the Common Model instance. | | `MODEL_NOT_FOUND` | Error | The ID of the field does not refer to an existing model. | Ensure that the UUID of the entry source matches a Merge common model ID. | | `MODEL_WITH_DUPLICATE_UNIQUE_FIELD_EXISTS` | Error | A model with a field which must be unique already exists. | If testing, ensure that none test data is used in subsequent requests. | | `PROVIDER_ERROR` | Error | An error from the third party platform's API prevented the request. | Use Debug Mode to get the relevant logs for troubleshooting. | | `RATE_LIMITED` | Error | The third-party platform ran into rate limiting issues. | Reach out to Merge for support at [help@merge.dev](mailto:help@merge.dev). | | `RELINK_NEEDED` | Error | This linked account needs to be relinked. | Navigate to [https://app.merge.dev/logs](https://app.merge.dev/logs) view the logs for the linked account to get more information. | | `UNSUPPORTED_OPERATION` | Error | Merge does not yet support this operation for the specified linked account. | Ensure the request you're making is compatible with the specified linked account. | | `UNSUPPORTED_TEST_REQUEST` | Error | The request you are making is only compatible with Production account. | Test account tokens may only be used to retrieve from the endpoints. If you need assistance with your setup, please reach out to [help@merge.dev](mailto:help@merge.dev). | ## Example error response Every failed write returns the same envelope. `problem_type` carries one of the codes above, `title` is its human-readable name, `detail` explains the failure, and `source` points at the field that caused it when Merge can identify one. #### 400 response to POST \`/tickets\` with a status Jira cannot transition to ```json { "warnings": [], "errors": [ { "source": null, "title": "Provider Error", "detail": "We've encountered the following error when trying to access the Jira API: The provided status_native value (\"fake\") is not a valid transition state for the ticket. The following status_native values are acceptable: ['Pending', 'Work in progress', 'Done']. Please check that the value you have entered is correct and try again.", "problem_type": "PROVIDER_ERROR" } ] } ``` A `PROVIDER_ERROR` wraps the third-party platform's own message, so its `detail` varies by integration. Match on `problem_type` rather than on the text of `detail`. > **Note** > > Writing a third-party platform's own enum values is covered in [Native enum values](/merge-unified/supplemental-data/native-enum-values).