Status Codes

When working with the Kibo Composable Commerce Platform (KCCP), client developers may encounter a number of response codes. These include generic HTTP statuses that apply to all API calls, as well as error codes that are unique to KCCP or occur only when using particular APIs. 

Generic HTTP Statuses

These OK and error responses may be encountered when working with any APIs.

Code Status Name Description
200 OK or Success Standard response for successful requests.
400 Bad Request The server cannot process the request due to a client error, such as incorrect syntax.
401 Unauthorized Authorization has been refused for those credentials.
403 Token Not Authorized The request was valid, but the user might not have the necessary permissions to make the call.
404 Not Found The requested resource could not be found.
405 Method Not Allowed Request method is not supported for the resource, such as a GET request on a form that requires POST.
409 Conflict Indicates a request conflict with current state of the server.
429 Too Many Requests Indicates that you have sent too many requests in a given amount of time. See API Best Practices for details about the rate limits. 
500 Internal Server Error An unexpected condition was encountered and no more specific message is suitable.
503 Service Unavailable The server is currently unavailable.

Core Errors and Exceptions

These error statuses are strings, not numeric error codes, that appear in many common exceptions throughout KCCP and especially eCommerce implementations. However, many are translated to corresponding HTTP responses and displayed with those generic error codes.

StatusDescription
UNEXPECTED_ERROR Error with seemingly no defined cause. May be displayed with HTTP 500.
SYSTEM_MAINTENANCE Error with seemingly no defined cause. May be displayed with HTTP 500.
EXCEEDED_MAX_RETRIES The maximum number of retries have been exceeded for the attempted operation.
UNAUTHORIZED Error with user authentication or authorization.
FORBIDDEN The system does not allow the action. The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated. There may or may not be an explanation provided; if not, it may be displayed with HTTP 404.
MISSING_OR_INVALID_PARAMETER The request could not be understood by the server due to malformed syntax; the request did not validate due to missing required parameters or invalid parameter values. Do not repeat the request without modifications.
VALIDATION_CONFLICT Request did not validate due to a conflict. May be displayed with HTTP 409.
ITEM_NOT_FOUND Unable to access resource data.
ITEM_ALREADY_EXISTS Tried to create an item that already exists.
INVALID_ACCESS_TOKEN There was a problem with the access token when accessing the operation. May be displayed with HTTP 401.
INVALID_CREDENTIALS A platform error indicating that the credentials are not appropriate for the call.
FEATURE_NOT_ENABLED The feature is not enabled for the site. May be displayed as HTTP 400.
PLAN_LIMIT_EXCEEDED A platform error indicating that API limits were exceeded.
PC_LOAD_LETTER Generic operation failure. May be displayed with HTTP 500.

Catalog and Product Admin API Errors

The Catalog and Product Admin APIs have unique numeric error codes, unlike the core responses listed above.

Error CodeStatus NameDescription
106 Attribute Set Null The attribute set was empty, null, or nothing.
111 Attribute In Attribute Set Collection Member Mismatch The attributes in the attribute set do not contain all members. Verify that all attributes belonging to the attribute set are present.
121 Data Retrieval Error An error has occurred when trying to retrieve the requested resource.
150 Record Already Exists Record already exists.
160 Referential Integrity Error Referential integrity error.

There are other statuses that may be returned with a corresponding HTTP error, such as HTTP 404, that provide more detail about the resource that was either not found or caused the error.

StatusDescription
AttributeSetNotFound An attribute set was not found.
AttributeGroupNotFound An attribute group was not found.
AttributeNotFound An attribute was not found.
AttributeSetLocalizedContentNotFound Localized content, such as values or alternate names, were not found for an attribute set in the call.
AttributeGroupLocalizedContentNotFound Localized content, such as values or alternate names, were not found for an attribute group in the call.
AttributeLocalizedContentNotFound Localized content, such as values or alternate names, were not found for an attribute in the call.
AttributeInAttributeSetNotFound An attribute record specified in a set could not be found.
AttributeInAttributeSetSequenceNotDefined A sequence was not defined for an attribute within a set. This should include the attribute ID.
ItemNotFound An item record was not found. This should include the item identifier.
MissingRequiredInputError A required field was not provided. This should include the field name.
ValueOutOfRange The value of a particular field was out of the allowed range. This should include the field name.
AttributeLocalizedContentAlreadyExists A localized value for an attribute that the call attempted to create already exists. This should include the locale code and attribute ID.
ProductVariationProductCodeAlreadyExists The variation product code that the call attempted to generate already exists. This should include the SKU and variation key.
AttributeStillAssignedToProducts An attribute is assigned to products and cannot be edited or deleted through the attempted call until it has been removed from the products. This should include the attribute ID and the number of products.
AttributeValueStillAssignedToProducts An attribute value is assigned to products and cannot be edited or deleted through the attempted call until it has been removed from the products. This should include the attribute ID, attribute value, and the number of products.
Conflict A generic conflict with no more specific error code.

CommerceRuntime API Errors

There is only one error code that is unique to the CommerceRuntime APIs. This group of APIs includes the Order, Payment, and Return APIs used with OMS and eCommerce, as well as the eCommerce Cart and Checkout APIs. However, this particular error usually only applies to imported orders in OMS implementations.

Error CodeDescription
5013 An imported OMS order failed to be accepted. This may be due to an error in order validation.

Inventory API Errors

While the Inventory API usually returns generic HTTP responses, it has a unique version of HTTP 404 that specifies exactly which resource could not be found. An HTTP 404 response may be presented with any of the following status names, depending on whether the failure was due to an unknown bin, group of bins, settings, or inventory job:

  • Bin Not Found
  • Bins Not Found
  • Export Setting Not Found
  • No Settings Found
  • Job Not Found

Other APIs and Gateways

There are no unique errors for Customer, Location, ShippingRuntime, ShippingAdmin, SiteSettings, or AdminUser APIs. When calling these APIs, the generic HTTP response codes and common exceptions can be expected.

Payment gateways may have their own unique response codes. For example, Authorize.Net may return an error code of “32: The merchant password is invalid or not present.” These codes are not defined by KCCP, but rather set by the payment providers. See the appropriate payment provider’s own documentation for details about their response codes if needed.