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

Status	Description
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 Code	Status	Description
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.

Status	Description
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 Code	Description
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.