Connect API Errors

Connect Add-On

Common HTTP error codes returned by the Connect API and their meaning.

Error responses have the same overall structure across the different commercetools APIs. General errors, such as ConcurrentModification, are returned across all APIs. API-specific errors are returned only for a specific set of endpoints and update actions.

General errors

400 Bad Request

The following general error codes can appear in responses with the HTTP status code 400:

InvalidJsonInput

Returned when an invalid JSON input has been sent. Either the JSON is syntactically incorrect or does not conform to the expected shape (for example is missing a required field).

The client application should validate the input according to the constraints described in the error message before sending the request.

code​
String​
"InvalidJsonInput"
message​
String​
"Request body does not contain valid JSON."
detailedErrorMessage​
String​

Further explanation about why the JSON is invalid.

InvalidQueryParam

Returned when an invalid query parameter has been sent.

code​
String​
"InvalidQueryParam"
message​
String​
"Request query param is not valid"
detailedErrorMessage​
String​

Further explanation about why the query parameter is invalid.

InvalidPathParam

Returned when an invalid path parameter has been sent.

code​
String​
"InvalidPathParam"
message​
String​
"Request path param is not valid"
detailedErrorMessage​
String​

Further explanation about why the path parameter is invalid.

DuplicateField

Returned when a field value conflicts with an existing value causing a duplicate.

code​
String​
"DuplicateField"
message​
String​
"A duplicate value $duplicateValue exists for field $field."
field​
String​

Name of the conflicting field.

duplicateValue​
Any​

Conflicting duplicate value.

FieldValueNotFound

Returned when a value for a field is not found.

code​
String​
"FieldValueNotFound"
message​
String​
"The value $value for the $field field was not found"
field​
String​

Name of the field.

value​
Any​

Conflicting value.

GitRepositoryNotReachableError

Returned when the GitHub repository is unreachable or not found.

code​
String​
"GitRepositoryNotReachable"
message​
String​
"Repository with the tag is not reachable"

401 Unauthorized

Returned when the client cannot be authenticated.

code​
String​
"AuthenticationError"
message​
String​
"Bad credentials or Client ID is not defined"

403 Forbidden

Returned when the client does not have sufficient permissions for this operation.

code​
String​
"AuthorizationError"
message​
String​
"Access denied"

404 Not Found

The following general error codes can appear in responses with the HTTP status code 404:

ResourceNotFound

Returned when the resource addressed by the request URL does not exist.

code​
String​
"ResourceNotFound"
message​
String​
"Deployment with id=$resourceId or key=$resourceKey does not exist"

409 Conflict

The following general error codes can appear in responses with the HTTP status code 409:

ConcurrentModification

Returned when the request conflicts with the current state of the involved resources. Typically, the request attempts to modify a resource that is out of date (that is modified by another client since it was last retrieved). The client application should resolve the conflict (with or without involving the end user) before retrying the request.

code​
String​
"ConcurrentModification"
message​
String​
"Object id=$resourceId or key=$resourceKey has a different version than expected. Expected: $expectedVersion - Actual: $currentVersion)"
expectedVersion​
Int64​

Expected version of the resource.

currentVersion​
Int64​

Current version of the resource.

500 Internal Server Error

The following general error codes can appear in responses with the HTTP status code 500:

General

Returned when a server-side problem occurs before or after data persistence. In some cases, the requested action may successfully complete after the error is returned. Therefore, it is recommended to verify the status of the requested resource after receiving a 500 error.

If you encounter this error, report it to the commercetools support team.
code​
String​
"General"
message​
String​
Description about any known details of the problem, for example, "Write operations are temporarily unavailable".

502 Bad Gateway

The following general error codes can appear in responses with the HTTP status code 502:

BadGateway

Returned when a server-side problem is caused by scaling infrastructure resources.

The client application should retry the request with exponential backoff up to a point where further delay is unacceptable.

code​
String​
"BadGateway"
message​
String​

Plain text description of the error.

API-specific errors

Connectors

400 Bad Request

DeploymentApplicationDoesNotExist

Returned when trying to get a log by application name, and the application does not exist on the Connector.

code​
String​
"DeploymentApplicationDoesNotExist"
message​
String​
"Deployment does not have an application named $resourceName."

DeploymentLogInvalidDate

Returned when trying to get a log with invalid start date or end date.

code​
String​
"DeploymentLogInvalidDate"
message​
String​
"Invalid start/end date"

DeploymentLogInvalidPageToken

Returned when trying to get a log with invalid page token.

code​
String​
"DeploymentLogInvalidPageToken"
message​
String​
"Invalid page token: $pageToken"

DeploymentLogMissingApplicationName

Returned when trying to get a log from an AWS deployment and an application name was not provided.

code​
String​
"DeploymentLogMissingApplicationName"
message​
String​
"Missing application name when fetching deployment logs"

ConnectorAlreadyCertified

Returned when trying to certify a Connector that is already certified.

The error is returned as a failed response to the Publish update action only when certification is required.
code​
String​
"ConnectorAlreadyCertified"
message​
String​
"The ConnectorStaged is already certified"

ConnectorReferenceNotFoundError

Returned when the referenced Connector was not found.

code​
String​
"ConnectorReferenceNotFound"
message​
String​
"Connector '$identifier' with version $version not found"

ConnectorSpecificationFileNotFoundError

Returned when the Connector specification file was not found.

code​
String​
"ConnectorSpecificationFileNotFound"
message​
String​
"The file connect.yaml at $url with the tag $tag was not found"

ConnectorSpecificationFileNotValidError

Returned when the Connector specification file is not valid.

code​
String​
"ConnectorSpecificationFileNotValid"
message​
String​
"The file connect.yaml at $url with the tag $tag is not valid"

ConnectorStagedInCertification

Returned when trying to publish a Connector that requires certification but is already in the certification process.

The error is returned as a failed response to the Publish update actiononly when certification is required.
code​
String​
"ConnectorStagedInCertification"
message​
String​
"The ConnectorStaged is already in certification"

ConnectorStagedNotPreviewable

Returned when a ConnectorStaged to be deployed is not previewable.

The error is returned as a failed response to the Create a Deployment request.
code​
String​
"ConnectorStagedNotPreviewable"
message​
String​
"Connector id=$resourceId or key=$resourceKey with version $version is not previewable"

ConnectorStagedNotPrivate

Returned when attempting to change the privateProjects of a non-private ConnectorStaged.
The error is returned as a failed response to the Add Project to Private Connector and Remove Project from Private Connector update actions.
code​
String​
"ConnectorStagedNotPrivate"
message​
String​
"The operation is not valid because ConnectorStaged with id=$resourceId or key=$resourceKey is not private"

ConnectorStagedPreviewRequestUnderProcess

Returned when attempting to request previewable status of a ConnectorStaged that is currently being reviewed for previewable status.

The error is returned as a failed response to the Preview Connector update action.
code​
String​
"ConnectorStagedPreviewRequestUnderProcess"
message​
String​
"The ConnectorStaged preview request is already in progress"

Deployments

400 Bad Request

DeploymentUnsupportedRegion

Returned when the Deployment region is not supported.

The error is returned as a failed response to the Create a Deployment request.
code​
String​
"DeploymentUnsupportedRegion"
message​
String​
"Deployment unsupported region $region"

DeploymentUnknownApplicationConfiguration

Returned when the Deployment contains configuration values that are not defined in the Connect application's connect.yaml file.

The error is returned as a failed response to the Redeploy update action and Create a Deployment request.
code​
String​
"DeploymentUnknownApplicationConfiguration"
message​
String​
"Deployment does not require configuration for application named '$unknownApplicationName'."

DeploymentUnknownApplicationConfigurationKey

Returned when the Deployment contains a configuration key that is not defined in the Connect application's connect.yaml file.

The error is returned as a failed response to the Redeploy update action and Create a Deployment request.
code​
String​
"DeploymentUnknownApplicationConfigurationKey"
message​
String​
"Deployment does not require (secret|standard) configuration with key $configurationKey for application named $applicationName."

DeploymentInvalidStatusTransition

Returned when the Deployment operation results in a invalid status transition.

The error is returned as a failed response to the Redeploy update action.
The message will contain Already queued, Already deploying, or Already undeploying based on the DeploymentStatus of the Deployment.
code​
String​
"DeploymentInvalidStatusTransition"
message​
String​
"Invalid status change: Already deploying"

DeploymentMissingGlobalConfigurationKey

Returned when a required global configuration key is missing.

code​
String​
"DeploymentMissingGlobalConfigurationKey"
message​
String​
"Deployment global configuration requires (secret|standard) with key $configurationKey."

DeploymentUnknownGlobalConfigurationKey

Returned when attempting to provide a nonexistent global configuration.

code​
String​
"DeploymentUnknownGlobalConfigurationKey"
message​
String​
"Deployment global configuration does not require (secret|standard) with key $configurationKey."

DeploymentEmptyRequiredGlobalConfigurationKey

Returned when a required global configuration key has an empty value.

code​
String​
"DeploymentEmptyRequiredGlobalConfigurationKey"
message​
String​
"Deployment requires a non empty value for (secret|standard) global configuration with key $configurationKey."

422 Unprocessable Content

DeploymentApplicationDoNotBelong

Returned when attempting to add an application that does not belong to the Deployment.

code​
String​
"DeploymentApplicationDoNotBelong"
message​
String​
"Deployment with id=$resourceId or key=$resourceKey does not include application: $applicationName"

DeploymentApplicationRequired

Returned when a Deployment does not contain any applications.

code​
String​
"DeploymentApplicationRequired"
message​
String​
"A Deployment requires at least one application"

DeploymentConnectorUpdateFailure

Returned when updating a Connector fails during redeployment.
code​
String​
"DeploymentConnectorUpdateFailure"
message​
String​
"Deployment with id=$resourceId or key=$resourceKey failed while trying to update Connector id=$resourceId or key=$resourceKey (cause: $cause)"

DeploymentProductionDeactivated

Returned as a failed response to the Create a Deployment request when deployments to production are disabled for the Project.
code​
String​
"DeploymentProductionDeactivated"
message​
String​
"Deployments to production are disabled for this Project. Please contact support to enable production deployments."

DeploymentInvalidType

Returned when the provided deployment type is not valid for the referenced Connector.
The error is returned as a failed response to the Create a Deployment request.
code​
String​
"DeploymentInvalidType"
message​
String​
"The Connector id=$resourceId or key=$resourceKey cannot be deployed as a '(preview|sandbox|production)' type. Only '(preview|sandbox|production)' types are allowed."

Representations

ErrorResponse

Base representation of an error response containing common fields to all errors.

statusCode​
Int​

HTTP status code corresponding to the error.

message​
String​
First error message in the errors array.
errors​
Array of ErrorObject​

Errors returned for a request.

A single error response can contain multiple errors if the errors are related to the same HTTP status code such as 400.
Example: json
{
  "statusCode": 400,
  "message": "First error message.",
  "errors": [
    {
      "code": "InvalidJsonInput",
      "message": "First error message.",
      "detailedErrorMessage": ""
    },
    {
      "code": "InvalidJsonInput",
      "message": "Second error message.",
      "detailedErrorMessage": ""
    }
  ]
}

ErrorObject

Represents a single error. Multiple errors may be included in an ErrorResponse.
code​
String​

Error identifier.

message​
String​

Plain text description of the cause of the error.

//​
Any string parameter matching this regular expression​

Error-specific additional fields.