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