Connect API Errors

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

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

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.

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 credientals 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
Int

Expected version of the resource.

currentVersion
Int

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 Connect 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

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"

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"

DeploymentMustIncludeApplication

Returned when attempting to remove an application that belongs to the Deployment.

code
String
"DeploymentMustIncludeApplication"
message
String

"Deployment with id=$resourceId or key=$resourceKey must include application: $applicationName"

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)"