Errors

Common HTTP error codes returned by the Checkout APIs and their meaning.

Error responses have the same overall structure across Checkout APIs. General errors, such as ResourceNotFound are returned for all APIs. API-specific errors, are only returned for specific endpoints.

General errors

400 Bad Request -RequiredField -DuplicateFieldWithConflictingResource -InvalidInput -InvalidJsonInput -InvalidOperation -InvalidField -MaxResourceLimitExceeded -ReferencedResourceNotFound -SyntaxError -MissingProjectKey

404 Not Found -ResourceNotFound

409 Conflict

ConcurrentModification

503 Service Unavailable -ServiceUnavailableError

500 Internal Server Error -GeneralError

400 Bad Request

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

RequiredField

Returned when a value is not defined for a required field.

`code` String	`"RequiredField"`
`message` String	`"A value is required for field $field."`
`field` String	Name of the field missing the value.

DuplicateFieldWithConflictingResource

Returned when a field value conflicts with an existing value stored in a particular resource causing a duplicate.

`code` String	`"DuplicateFieldWithConflictingResource"`
`message` String	`"A duplicate value $duplicateValue exists for field $field in request."`

InvalidInput

Returned when an invalid input has been sent.

`code` String	`"InvalidInput"`
`message` String	Description of the invalid input error.

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, it 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.

InvalidOperation

Returned when the resources involved in the request are not in a valid state for the operation.

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

`code` String	`"InvalidOperation"`
`message` String	Description of the error.

InvalidField

Returned when a field has an invalid value.

`code` String	`"InvalidField"`
`message` String	`"The value $invalidValue is not valid for field $field."`
`field` String	Name of the field with the invalid value.
`invalidValue` Any	Value invalid for the field.
`allowedValues` Array of String	Fixed set of allowed values for the field, if any.

MaxResourceLimitExceeded

Returned when a resource type cannot be created as it has reached its limits.

The limits must be adjusted for this resource before sending the request again.

`code` String	`"MaxResourceLimitExceeded"`
`message` String	`"You have exceeded the limit of $limit resources of type $resourceTypeId."`
`limit` Float	The limit that was exceeded.
`resourceTypeId` String	The resource type that reached its limit.

ReferencedResourceNotFound

Returned when a resource referenced by a Reference or a ResourceIdentifier could not be found.

`id` String	Unique identifier of the referenced resource, if known.
`code` String	`"ReferencedResourceNotFound"`
`message` String	`"The referenced object of type $typeId $id \|\| key was not found. It either doesn't exist, or it can't be accessed from this endpoint (e.g., if the endpoint filters by store or customer account)."`
`typeId` String	Type of referenced resource.
`key` String	User-defined unique identifier of the referenced resource, if known.

SyntaxError

Returned when a Payment Predicate does not have the correct syntax.

`code` String	`"SyntaxError"`
`message` String	`"Syntax error while parsing $fieldDefinition."`

MissingProjectKey

Returned when the project key is missing from the request.

`code` String	`"MissingProjectKey"`
`message` String	`"Missing project key in the request path."`

404 Not Found

The following error code 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	`"The Resource with $resourceIdentifier $resourceId was not found."`
`resourceIdentifier` String	The identifier type used (e.g., `id`, `key`).
`resourceId` String	The actual identifier value.

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 $resourceId has a different version than expected. Expected: $expectedVersion - Actual: $currentVersion."`
`resourceId` String	The ID of the resource that has a version conflict.
`expectedVersion` Int64	Expected version of the resource.
`currentVersion` Int64	Current version of the resource.

503 Service Unavailable

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

ServiceUnavailableError

Returned when the service is unavailable, for example when the Notification Service is down.

`code` String	`"ServiceUnavailable"`
`message` String	`"Service is unavailable."`

500 Internal Server Error

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

GeneralError

Returned when a server-side problem occurs. 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"`.

API-specific errors

The following errors are specific to certain API endpoints or operations.

Payment Intents

400 Bad Request -MultipleActionsNotAllowed

400 Bad Request

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

MultipleActionsNotAllowed

Returned when actions in the request body contains more than one object.

`code` String	`"MultipleActionsNotAllowed"`
`message` String	`"Actions accepts only one action at time. Array size must be 1."`

Transactions

502 Bad Gateway -ConnectorFailed -PaymentFailure

502 Bad Gateway

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

ConnectorFailed

Returned when the payment Connector cannot be reached.

`code` String	`"ConnectorFailed"`
`message` String	`"The connector could not be reached."`

PaymentFailure

Returned when the payment cannot be completed successfully.

`code` String	`"PaymentFailure"`
`message` String	`"Payment could not be completed successfully."`

General errors.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

400 Bad Request.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

RequiredField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

DuplicateFieldWithConflictingResource.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

InvalidInput.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

InvalidJsonInput.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

InvalidOperation.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

InvalidField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

MaxResourceLimitExceeded.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ReferencedResourceNotFound.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

SyntaxError.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

MissingProjectKey.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

404 Not Found.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ResourceNotFound.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

409 Conflict.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ConcurrentModification.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

503 Service Unavailable.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ServiceUnavailableError.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

500 Internal Server Error.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

GeneralError.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

API-specific errors.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Payment Intents.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

400 Bad Request.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

MultipleActionsNotAllowed.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Transactions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

502 Bad Gateway.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

ConnectorFailed.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

PaymentFailure.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

General errors

400 Bad Request

RequiredField

DuplicateFieldWithConflictingResource

InvalidInput

InvalidJsonInput

InvalidOperation

InvalidField

MaxResourceLimitExceeded

ReferencedResourceNotFound

SyntaxError

MissingProjectKey

404 Not Found

ResourceNotFound

409 Conflict

ConcurrentModification

503 Service Unavailable

ServiceUnavailableError

500 Internal Server Error

GeneralError

API-specific errors

Payment Intents

400 Bad Request

MultipleActionsNotAllowed

Transactions

502 Bad Gateway

ConnectorFailed

PaymentFailure