OCAPI HTTP Status Codes and Faults

To help you handle errors and special cases, the Open Commerce API returns HTTP status codes and faults.

The following table lists the HTTP status codes and their typical use cases:

HTTP status codeCases
200 (OK)GET, PUT, or POST request successfully completed.
201 (Created)POST or PUT request successfully created a resource or relationship resource.
204 (No Content)DELETE, HEAD, or OPTIONS (or less typically a POST, PUT, or PATCH) request successfully completed and returned no content.
400 (Bad Request)Request contains invalid information, such as malformed parameters, malformed header values, or a malformed body.
401 (Unauthorized)Request isn’t authorized to be processed.
403 (Forbidden)Request is declined by the server.
404 (Not Found)Requested resource doesn’t exist.
405 (Method Not Allowed)Resource doesn’t support supplied HTTP method.
409 (Conflict)The request couldn’t be completed due to a conflict with the current state of the resource.
412 (Precondition Failed)PATCH request provided an outdated last-known base point, which means the resource was changed on server, possibly by a concurrent request.
415 (Unsupported Media Type)Media type specified in "format" request parameter (or Accept header) isn’t supported.
500 (Internal Server Error)Request can’t be fulfilled because of an unexpected condition on the server.

For status codes greater than or equal to 400, the API returns a fault document:

The fault document contains a type identifier, a readable message and a arguments map listing the values integrated into the message. The keys used in the map follow the sequence '0', '1', '2' unless otherwise specified in the documentation. The value can be null. The possible values of the type property are listed below with details of the format used for each value:

Value typeValue formatExample
booleantrue/false{"type":"boolean","value":true}
dateString format 'YYYY-mm-DD' where Y=year, m=month, D=day{"type":"date","value":"2015-07-01"}
datetimeString format 'YYYY-mm-DDTHH:MM.mmmZ' where Y=year, m=month, D=day, H=hours, M=minutes, S=seconds, m=millis and Z is timezone, one of 'Z' for UTC or the offset such as +01:00 or -03:00{"type":"datetime","value":"2015-07-01T08:22:15.000+02:00"}
decimalNumeric decimal{"type":"decimal","value":256.78}
integerNumeric integer{"type":"integer","value":141}
stringPlain string{"type":"string","value":"A fox flew"}
timeString format 'HH:MM.mmm' where H=hours, M=minutes, S=seconds and m=millis{"type":"time","value":"08:15:24.500"}

The following sections provide detailed information about faults returned for different HTTP status codes.

Fault typeSample fault message
ConstraintViolationException'count' value constraint violated. Expected value is between '(1..200)'.
IllegalHttpMethodOverrideExceptionOnly HTTP methods 'PUT', 'PATCH', 'DELETE' can be overwritten.
InvalidBillingAddressExceptionInvalid billing address.
InvalidBundledProductItemCountExceptionNumber of update bundled product items doesn't match number of server bundled product items.
InvalidCouponItemExceptionCoupon code 'SUMMER2012' is invalid.
InvalidCustomerInformationExceptionInvalid customer info 'email' address.
InvalidCustomPropertyExceptionInvalid custom property in request.
InvalidExpandParameterExceptionInvalid expand parameter 'foo' found.
InvalidMessageExceptionMandatory attribute 'email' must not be null or empty
InvalidOptionItemExceptionProduct option 'warranty' isn’t supported.
InvalidPasswordExceptionPassword doesn't match acceptance criteria.
InvalidPaymentMethodExceptionPayment method with id 'Paypal' is unknown or not applicable to basket.
InvalidProductItemExceptionProduct '0815' is unknown, offline or not assigned to site catalog.
InvalidShippingAddressExceptionInvalid shipping address.
InvalidShippingMethodIdExceptionShipping method with id 'UPS' is unknown or not applicable to basket.
InvalidUsernameExceptionUsername doesn't match acceptance criteria.
MalformedLocaleExceptionMalformed locale value 'en+US'.
MalformedMediaTypeExceptionMalformed Content-Type 'foo' in header.
MalformedParameterExceptionMalformed value '10p' for parameter 'count'.
MalformedPathVariableExceptionMalformed path variable '(123,456'. The correct syntax for multiple ids is: (id1,id2,id3). If the characters ( ) , are part of the id itself, they have to be URL encoded.
MalformedPriceRefinementExceptionMalformed price refinement '(0..5x)'. Expected something like '(0..100)'.
MalformedSelectorExceptionMalformed property selector '(name,id'.
MissingClientIdExceptionMissing client id.
MissingParameterExceptionMissing parameter 'campaign_id'.
ProductItemNotAvailableExceptionProduct '017845724321' isn’t available for quantity '5'.
QuotaExceededExceptionMaximum number of product items per basket exceeded.
UnknownLocaleExceptionThe locale 'foo is unknown.
UnknownParameterExceptionUnknown parameter 'foo'.
UnsupportedLocaleExceptionThe locale 'de-DE' isn’t supported/activated for this site.
UsernameAlreadyInUseExceptionUsername is already in use.
Fault typeSample fault message
InvalidSecureTokenExceptionSession may have been hijacked.
UnauthorizedExceptionUnauthorized request for resource '/s/SiteGenesis/dw/shop/v24_5/basket/this/checkout/submit' from client '[your_own_client_id]'.
UnauthorizedOriginExceptionUnauthorized origin 'foo.com' from client '[your_own_client_id]'.
UnknownClientIdExceptionUnknown client id 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'.
Fault typeSample fault message
SecureCommunicationRequiredExceptionSecure communication required.
SiteOfflineExceptionThe site 'SiteGenesis' is offline and can't be accessed.
Fault typeSample fault message
InvalidVersionExceptionInvalid version syntax 'v24.5'. Provide a valid version like 'v24_5'.
NotFoundExceptionNo product with id '0815' for site 'SiteGenesis' found.
ResourcePathNotFoundExceptionIf the requested URL matches the Commerce Cloud Digital Rest URL pattern, but the resource path is unknown that is, /dw/shop/v24_5/unknown/123.
UnknownVersionExceptionUnknown version 'v33.33'. Provide a valid version.
Fault typeSample fault message
MethodNotAllowedExceptionMethod 'DELETE' not allowed.
Fault typeSample fault message
NotAcceptableExceptionUnsupported charset 'iso-8859-1' in Accept-Charset header. Note: Only UTF-8 charset is supported.
Fault typeSample fault message
RequestEntityTooLargeExceptionRequest body size limit of 5 MB has been exceeded.
Fault typeSample fault message
RequestUriTooLongExceptionRequest URL length limit of 2000 characters has been exceeded.
Fault typeSample fault message
UnsupportedMediaTypeExceptionUnsupported document format 'pdf'.
Fault typeSample fault message
InternalErrorExceptionInternal Server Error.