Writes warnings and errors reference

Warning and error codes

This is a reference list of all possible errors and warnings returned by Merge’s API’s POST endpoints.

For more information on errors and warnings related to POST requests to Merge, check out the guide on Troubleshooting Writes.

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 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 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 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.
`RELINK_NEEDED`	Error	This linked account needs to be relinked.	Navigate to 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.

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

{
  "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.

Writing a third-party platform’s own enum values is covered in Native enum values.