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 code	Cases
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 type	Value format	Example
boolean	true/false	{"type":"boolean","value":true}
date	String format 'YYYY-mm-DD' where Y=year, m=month, D=day	{"type":"date","value":"2015-07-01"}
datetime	String 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"}
decimal	Numeric decimal	{"type":"decimal","value":256.78}
integer	Numeric integer	{"type":"integer","value":141}
string	Plain string	{"type":"string","value":"A fox flew"}
time	String format 'HH:MM.mmm' where H=hours, M=minutes, S=seconds and m=millis	{"type":"time","value":"08:15:22.000"}

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

Fault type	Sample fault message
ConstraintViolationException	'count' value constraint violated. Expected value is between '(1..200)'.
IllegalHttpMethodOverrideException	Only HTTP methods 'PUT', 'PATCH', 'DELETE' can be overwritten.
InvalidBillingAddressException	Invalid billing address.
InvalidBundledProductItemCountException	Number of update bundled product items doesn't match number of server bundled product items.
InvalidCouponItemException	Coupon code 'SUMMER2012' is invalid.
InvalidCustomerInformationException	Invalid customer info 'email' address.
InvalidCustomPropertyException	Invalid custom property in request.
InvalidExpandParameterException	Invalid expand parameter 'foo' found.
InvalidMessageException	Mandatory attribute 'email' must not be null or empty
InvalidOptionItemException	Product option 'warranty' isn’t supported.
InvalidPasswordException	Password doesn't match acceptance criteria.
InvalidPaymentMethodException	Payment method with id 'Paypal' is unknown or not applicable to basket.
InvalidProductItemException	Product '0815' is unknown, offline or not assigned to site catalog.
InvalidShippingAddressException	Invalid shipping address.
InvalidShippingMethodIdException	Shipping method with id 'UPS' is unknown or not applicable to basket.
InvalidUsernameException	Username doesn't match acceptance criteria.
MalformedLocaleException	Malformed locale value 'en+US'.
MalformedMediaTypeException	Malformed Content-Type 'foo' in header.
MalformedParameterException	Malformed value '10p' for parameter 'count'.
MalformedPathVariableException	Malformed 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.
MalformedPriceRefinementException	Malformed price refinement '(0..5x)'. Expected something like '(0..100)'.
MalformedSelectorException	Malformed property selector '(name,id'.
MissingClientIdException	Missing client id.
MissingParameterException	Missing parameter 'campaign_id'.
ProductItemNotAvailableException	Product '017845724321' isn’t available for quantity '5'.
QuotaExceededException	Maximum number of product items per basket exceeded.
UnknownLocaleException	The locale 'foo is unknown.
UnknownParameterException	Unknown parameter 'foo'.
UnsupportedLocaleException	The locale 'de-DE' isn’t supported/activated for this site.
UsernameAlreadyInUseException	Username is already in use.

Fault type	Sample fault message
InvalidSecureTokenException	Session may have been hijacked.
UnauthorizedException	Unauthorized request for resource '/s/SiteGenesis/dw/shop/v23_1/basket/this/checkout/submit' from client '[your_own_client_id]'.
UnauthorizedOriginException	Unauthorized origin 'foo.com' from client '[your_own_client_id]'.
UnknownClientIdException	Unknown client id 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'.

Fault type	Sample fault message
SecureCommunicationRequiredException	Secure communication required.
SiteOfflineException	The site 'SiteGenesis' is offline and can't be accessed.

Fault type	Sample fault message
InvalidVersionException	Invalid version syntax 'v23.1'. Provide a valid version like 'v21_2'.
NotFoundException	No product with id '0815' for site 'SiteGenesis' found.
ResourcePathNotFoundException	If the requested URL matches the Commerce Cloud Digital Rest URL pattern, but the resource path is unknown that is, /dw/shop/v23_1/unknown/123.
UnknownVersionException	Unknown version 'v33.33'. Provide a valid version.

Fault type	Sample fault message
MethodNotAllowedException	Method 'DELETE' not allowed.

Fault type	Sample fault message
NotAcceptableException	Unsupported charset 'iso-8859-1' in Accept-Charset header. Note: Only UTF-8 charset is supported.

Fault type	Sample fault message
RequestEntityTooLargeException	Request body size limit of 5 MB has been exceeded.

Fault type	Sample fault message
RequestUriTooLongException	Request URL length limit of 2000 characters has been exceeded.

Fault type	Sample fault message
UnsupportedMediaTypeException	Unsupported document format 'pdf'.

Fault type	Sample fault message
InternalErrorException	Internal Server Error.