HTTP API Errors

Common HTTP error codes

400 Bad Request

Affected HTTP methods: GET, POST, 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, DELETE

A 401 indicates that the request is not properly authenticated.

403 Forbidden

Affected HTTP methods: GET, POST, DELETE

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

404 Not Found

Affected HTTP methods: GET, POST, DELETE

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

409 Conflict

Affected HTTP methods: POST, DELETE

A 409 indicates that the current version of the resource targeted by the request (with the intention to modify or delete it) is different from that provided in the request. In response to this, the client will usually want to request the newest version of the resource to see what has been changed and decide what changes to apply to the newest version.

A 409 Conflict indicates a concurrent modification and usually occurs on a versioned resource, which requires the client to provide the version of the resource to perform a change.

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

502 Bad Gateway

Affected HTTP methods: GET, POST, DELETE

A 502 indicates that a request failed due to a server-side problem caused by platform scaling. The client application should retry the request with exponential backoff up to a point where further delay is unacceptable.

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" }
  ]
}

The error response always has the following fields:

• statusCode: the HTTP status code corresponding to the error.
• message: The message field of the first error in the errors array.
• errors: An array containing all errors which occured for this request. Each error contains the following fields:
  • code: a String error identifier. You can find more information about an error on this page using its code.
  • message: A plain language description of the cause of the error.

Some errors have additional fields beside code and message and are documented appropriately.

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, for example multiple errors related to a 400.

OAuth related errors

Errors related to authentication and authorization also conform to the OAuth 2.0 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.

Errors from an API Extension

API Extensions can validate API calls and reject updates resulting in a 400 Bad Request response. API Extensions also have Error Cases.

When an API Extension is involved in the error, the errorByExtension field is added to the error response. The errorByExtension field contains the id and (if set) the key of the API extension. If the API Extension returnslocalizedMessage or the extensionExtraInfo fields in a Validation Error, they are also added to the error response.

{
  "statusCode": 400,
  "message": "The API Extension found your request to be invalid.",
  "errors": [
    {
      "code": "InvalidInput",
      "message": "The API Extension found your request to be invalid.",
      "localizedMessage": {
        "en": "The API Extension found your request to be invalid.",
        "de": "Die API Extension hat ihre Anfrage als invalid beurteilt."
      },
      "extensionExtraInfo": {
        "anotherField": ["Foo", "Bar"],
        "baz": true
      },
      "errorByExtension": {
        "id": "<extension-id>",
        "key": "my-extension"
      }
    }
  ]
}

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 the 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 the 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:

• AnonymousIdAlreadyInUse
  The anonymous ID is already in use by another resource.
  The client application should choose another anonymous ID or retreive an automatically generated one.

• 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.

• DuplicateFieldWithConflictingResource
  A value for a field conflicts with an existing duplicate value stored in a particular resource.
  Extra fields:

  • field - String
    The name of the field.
  • duplicateValue - *
    The offending duplicate value.
  • conflictingResource - Reference to a conflicting resource

• FeatureRemoved
  The resource requested was removed.
  The client application should use the feature recommended by the error message instead.

• 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.

• InvalidJsonInput
  Invalid JSON input has been sent to the service. Either the JSON is syntactically not correct, or the JSON 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.

• InvalidOperation
  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.

• 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.

• InternalConstraintViolated
  The discount code specified was never applied and cannot be updated.

• MaxResourceLimitExceeded
  No more resources of the type in this request can be created. Limits configuration should be adjusted for this resource before sending the request again.
  Extra fields:

  • exceededResource - ReferenceType
    The resource type that reached its maximum value of configured elements, for example 100 zones per project, so no additional objects can be created.

• ObjectNotFound
  The requested resource was not found.

• ReferenceExists
  A resource cannot be deleted because it is referenced by something else.

• ReferencedResourceNotFound
  A resource referenced by a Reference or a ResourceIdentifier could not be found.
  Extra fields:

  • typeId - ReferenceType
    The type of referenced resource.
  • id - String - Optional
    The unique ID of the referenced resource if known.
  • key - String - Optional
    The unique key of the referenced resource if known.

• RequiredField
  A required field is missing a value.
  Extra fields:

  • field - String
    The name of the field.

• ResourceSizeLimitExceeded
  The resource exceeds the maximum allowed size of 16 MB.

• SemanticError
  The predicate is not semantically correct.

• SyntaxError
  The search query or predicate does not have correct syntax.

• QueryTimedOut
  The query timed out. If your query constantly times out, please check that it follows the performance best practices.

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 resources. Typically, the request attempts to modify a resource that is out of date. Out of date means, that a ressource 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.

External OAuth error responses

The following error code is returned when an External OAuth Introspection endpoint triggered during an API request did not respond successfully.

502 or 504 External OAuth Failed

• ExternalOAuthFailed
  The External OAuth Introspection endpoint did not return a response within the time limit, or the response wasn't compliant with RFC 7662 (for example a HTTP status code like 500).

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

• EnumValueIsUsed
  When removing an EnumValue from a required attribute, but the EnumValue is still used by a product.

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.
  Extra fields on non-existent discount code

  • discountCode - String - discount code passed
  • reason - String - "DoesNotExist" Extra fields on discount code with invalid time range:
  • discountCode - String
    Discount code passed
  • dicountCodeId - String
    Discount Code ID
  • validFrom - DateTime - Optional
    Discount code is valid from this date.
  • validUntil - DateTime - Optional
    Discount code is valid till this date.
  • validityCheckTime - DateTime At what time the discount code validity check was performed.
  • reason - String - "TimeRangeNonApplicable"

• 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.

• MatchingPriceNotFound
  The product variant does not contain a Price for a selected currency and/or country, customer group or channel.
  Extra fields:

  • productId - Product ID
  • variantId - Integer
    Product Variant ID
  • currency - String - Optional
    A three-digit currency code as per ISO 4217.
  • country - String - Optional
    A two-digit country code as per ISO 3166-1 alpha-2.
  • customerGroup - Reference to a CustomerGroup - Optional
  • channel - Reference to a Channel - Optional

• MissingTaxRateForCountry
  The tax category of at least one of the lineItems, customLineItems, or the shippingInfo in the Cart is missing the TaxRate matching country and state given in the shippingAddress of that cart.
  Extra fields:

  • taxCategoryId - String
    ID of the Tax Category
  • country - String - Optional
    A three-digit currency code as per ISO 4217.
  • state - String - Optional
    The state in the country.

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.

• MissingTaxRateForCountry
  Tax category is missing the tax rate for country on some products in the customer cart.

• WeakPassword Password must contain at least 1 letter, 1 digit and 8 characters.

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.

Shipping Methods

400 Bad Request

• EditPreviewFailed
  To find the appropriate shipping methods for an OrderEdit a preview must be generated but if that fails the EditPreviewFailed is raised.

  Extra fields:

  • result - OrderEditPreviewFailure

Category Recommendations

403 Forbidden

• NotEnabled
  The category recommendations API is not yet enabled for your project. By default, the API is enabled for projects that match the activation criteria defined here.

  If you want to enable the API regardless, you can contact us via the platform support.

Product Projection Search

400 Bad Request

• SearchFacetPathNotFound
  The search facet path was not found.

• SearchExecutionFailure
  The search or GraphQL query did not complete due to an unexpected failure.

• SearchDeactivated
  Indexing of product information is currently deactivated for this project. Please activate it by calling Change Product Search Indexing Enabled with enabled set to true.

• SearchIndexingInProgress
  Indexing of product information has been activated for this project, but indexing is still in progress. Please try again in a few minutes.

Projects

400 Bad Request

• LanguageUsedInStores
  The specified language can not be deleted from the Project as long as it is used in a Store.

Stores

400 Bad Request

• ProjectNotConfiguredForLanguages
  Given languages are not supported by the project.
  Extra fields:

  • languages - Array of Strings
    IETF language tags of the languages that were supplied, but not supported by the project.

• MissingRoleOnChannel
  Required ChannelRole is missing on a given Channel.
  Extra fields:

  • channel - ResourceIdentifier of a Channel
    ResourceIdentifier of a given Channel.
  • missingRole - ChannelRole
    Required ChannelRole.

GraphQL

400 Bad Request

• QueryComplexityLimitExceeded
  The query has a complexity score equal or higher than 20 000.