HTTP API Errors

Common HTTP error codes used in the commercetools platform APIs and their meaning. For details about the structure and application-specific error-codes of a specific commercetools platform web service, consult the documentation dedicated to that service.

Common HTTP Error Codes

400 Bad Request

Affected HTTP methods: GET, POST, PUT, DELETE

A 400 is the most commonly expected error response and indicates that a request failed due to providing bad input. Bad input can be a malformed request body, missing required parameters, wrongly typed or malformed parameters or a parameter that references another resource that does not exist. Clients need to resolve the problems mentioned in the response before re-sending the request.

401 Unauthorized

Affected HTTP methods: GET, POST, PUT, DELETE

A 401 indicates that the request is not properly authenticated.

403 Forbidden

Affected HTTP methods: GET, POST, PUT, DELETE

A 403 indicates that the authenticated client is not allowed to perform the request.

404 Not Found

Affected HTTP methods: GET, POST, PUT, DELETE

A 404 indicates that the addressed resource was not found / does not exist.

409 Conflict

Affected HTTP methods: POST, PUT, DELETE

A 409 indicates that the resource targeted by the request (with the intention to modify or delete the resource), was modified since the last time the client has requested it. As a reaction, the client will usually want to request the newest version of the resource to see what has changed and may then decide to apply the same or other changes to the new version, or discard his changes entirely.

Conflicts indicate a concurrent modification and usually occur on versioned resources, for which the client has to include the version of the resource whenever he intends to apply modifications to it.

Whenever possible the HTTP response body contains the currentVersionfield (optional) like this:

{
  "statusCode": 409,
  "message": "Version mismatch. Concurrent modification.",
  "errors": [
    {
      "code": "ConcurrentModification",
      "message": "Version mismatch. Concurrent modification.",
      "currentVersion": 2
    }
  ]
}

500 Internal Server Error

Affected HTTP methods: GET, POST, PUT, DELETE

A 500 indicates that a request failed due to a server-side problem that needs to be resolved before subsequent requests can succeed. It either indicates a temporary unavailability or permanent server-side problem that needs to be reported and resolved.

Error responses

The general structure of error responses from the API is as follows:

{
  "statusCode": 400,
  "message": "First error message",
  "errors": [
   { "code":"SomeErrorCode", "message": "First error message" },
   { "code":"SomeErrorCode", "message": "Second error message" }
  ]
}

Note the following:

  • The statusCode is the same HTTP status code used in the response.
  • There is always at least one error present.
  • The first error message also appears on the top-level JSON object for ease of use.
  • Multiple errors with the same error code can appear.
  • Some errors may have additional fields besides code and message. If so, these are documented.

The following sections describe the possible errors in the following way:

  • <HTTP Status Code> - <Error Code>
    <Description>

The service always tries to report as many errors in a single response as possible, which is mainly the case for errors falling under the same HTTP status code, e.g. multiple errors related to a 400.

Errors related to authentication and authorization also conform to the ↗ OAuth2 specification . They additionally contain the field error and, if available, the field error_description.

{
    "statusCode": 401,
    "message": "This endpoint requires an access token. You can get one from the authorization server.",
    "errors": [{
      "code": "access_denied",
      "message": "This endpoint requires an access token. You can get one from the authorization server."
    }],
    "error": "access_denied",
    "error_description": "This endpoint requires an access token. You can get one from the authorization server."
}

Also note that error codes defined by the OAuth spec are not written in camelCase.

General

500 Internal Server Error

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

  • General
    A server-side problem occurred that is not further specified.
    These errors should be reported on our ↗ Support Portal .

503 Service Unavailable

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

  • OverCapacity
    The service is having trouble handling the load.
    The client application should retry the request with exponential backoff up to a point where further delay is unacceptable.

  • PendingOperation
    A previous conflicting operation is still pending and needs to finish before the request can succeed.
    The client application should retry the request with exponential backoff up to a point where further delay is unacceptable.
    If these errors persist, they should be reported on our ↗ Support Portal .

404 Not Found

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

  • ResourceNotFound
    The resource addressed by the request URL does not exist.

400 Bad Request

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

  • InvalidInput
    Invalid input has been sent to the service.
    The client application should validate the input according to the constraints described in the error message before sending the request.

  • InvalidOperation
    The resource(s) 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.

  • InvalidField
    A field has an invalid value.
    Extra fields:
    • field - String
      The name of the field.
    • invalidValue - *
      The invalid value.
    • allowedValues - Array of * - Optional
      A fixed set of allowed values for the field, if any.
  • RequiredField
    A required field is missing a value.
    Extra fields:
    • field - String
      The name of the field.
  • DuplicateField
    A value for a field conflicts with an existing duplicate value.
    Extra fields:
    • field - String
      The name of the field.
    • duplicateValue - *
      The offending duplicate value.

409 Conflict

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

  • ConcurrentModification
    The request conflicts with the current state of the involved resource(s). Typically, the request attempts to modify a resource that is out of date, i.e. that has been modified by another client since the last time it was retrieved. The client application should resolve the conflict (with or without involving the end-user) before retrying the request.

Extension Error Responses

The following error codes are returned when an API Extension triggered during an API request did not respond successfully.

502 Extension Bad Response

  • ExtensionBadResponse The response was not expected. Some examples include an unexpected HTTP status code like 500, or an invalid JSON response.

502 Extension Update Actions Failed

  • ExtensionUpdateActionsFailed An update action could not be properly applied. This would have resulted in a 400 Bad Request response if the same update action was sent from a regular client. An example is if an AddLineItem call references a product that doesn’t exist.

504 Extension No Response

  • ExtensionNoResponse The extension did not return a response within the time limit or could not be reached.

Products

400 Bad Request

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

  • DuplicatePriceScope
    A given price scope conflicts with an existing one. Every price of a product variant must have a distinct combination of currency, customer group, country and channel. These four properties constitute the scope of a price.
    Extra fields:
    • conflictingPrices - Array containing the two Prices conflicting with each others.
  • DuplicateVariantValues
    A given combination of variant values conflicts with an existing one. Every product variant must have a distinct combination of SKU, prices, and custom attribute values.
    Extra fields:
    • variantValues - The offending variant values:
      • sku - String - Optional
      • prices - Array of Price
      • attributes - Array of Attribute
  • DuplicateAttributeValue
    The Unique AttributeConstraint was violated.
    Extra fields:
    • attribute - Attribute
      The conflicting attribute.
  • DuplicateAttributeValues
    The CombinationUnique AttributeConstraint was violated.
    Extra fields:
    • attributes - Array of Attribute
      The conflicting CombinationUnique attributes.

Product Types

400 Bad Request

The following product type-specific error codes can appear in responses with the HTTP status code 400:

  • AttributeDefinitionAlreadyExists
    A given AttributeDefinition name conflicts with an already defined attribute.
    Extra fields:
    • conflictingProductTypeId - String - The ID of the product type containing the conflicting name
    • conflictingProductTypeName - String - The name of the product type containing the conflicting name
    • conflictingAttributeName - String - The name of the conflicting attribute
  • AttributeDefinitionTypeConflict
    A given AttributeDefinition name already exists on another product type with a different type.
    Extra fields:
    • conflictingProductTypeId - String - The ID of the product type containing the attribute with the same name but different type
    • conflictingProductTypeName - String - The name of the product type containing the attribute with the same name but different type
    • conflictingAttributeName - String - The name of the conflicting attribute
  • DuplicateEnumValues
    A given enum or lenum contains duplicate keys.
    Extra field:
    • duplicates - Array of String - The duplicate keys
  • EnumKeyAlreadyExists
    A given enum or lenum contains key that already exists.
    Extra fields:
    • conflictingEnumKey - String - The conflicting enum key
    • conflictingAttributeName - String - The name of the conflicting attribute
  • EnumKeyDoesNotExist
    The enum or lenum already contains a value with the given key.
    Extra fields:
    • conflictingEnumKey - String - The conflicting enum key
    • conflictingAttributeName - String - The name of the conflicting attribute
  • AttributeNameDoesNotExist
    An AttributeDefinition for the given attribute name does not exist.
    Extra fields:
    • invalidAttributeName - String - The non-existent attribute name
  • EnumValuesMustMatch
    When reordering enum or lenum values all existent values must be passed

Orders

400 Bad Request

The following order-specific error codes can appear in responses to Create Order from Cart requests with the HTTP status code 400:

  • OutOfStock
    Some of the ordered line items are out of stock at the time of placing the order.
    Extra fields:
    • lineItems - Array of String
      IDs of the line items that are out of stock.
    • skus - Array of String
      The skus of the line items that are out of stock.
  • PriceChanged
    The price, tax or shipping of some line items changed since the items were added to the cart.
    Extra fields:
    • lineItems - Array of String
      IDs of the line items for which the price or TaxRate changed.
    • shipping - Boolean
      True if the ShippingRate changed.
  • DiscountCodeNonApplicable
    The cart contains a discount code with a DiscountCodeState different from MatchesCart.

  • ShippingMethodDoesNotMatchCart
    The cart contains a ShippingMethod that is not allowed for the cart. In this case the ShippingMethodState value is DoesNotMatchCart.

  • InvalidItemShippingDetails
    A line item or custom line item has one or more shipping addresses set, but the quantity of that item does not match the sum of the quantities in its shipping details.
    Extra fields:
    • subject - String
      Either "LineItem" or "CustomLineItem".
    • itemId - String
      The id of the (custom) line item where the quantities set under ItemShippingDetails do not sum up to be equal to the (custom) line item quantity.

Customers

400 Bad Request

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

  • InvalidCredentials
    Account with the given credentials not found.
  • InvalidCurrentPassword
    The given current password does not match.

Product Discounts

404 Not Found

The following product discount specific error codes can appear in responses with the HTTP status code 404:

  • NoMatchingProductDiscountFound
    Couldn’t find a product discount that would have been applied to the given price for the selected variant.