OCAPI HTTP status codes and faults 19.10

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

HTTP status codes

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 new 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 is not authorized to be processed.
403 (Forbidden) Request is declined by the server.
404 (Not Found) Requested resource does not exist.
405 (Method Not Allowed) Resource does not support supplied HTTP method.
409 (Conflict) The request could not 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) is not supported.
500 (Internal Server Error) Request cannot be fulfilled because of an unexpected condition on the server.

Fault document

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

{
  "fault" : 
  { 
    "type" : "NotFoundException", 
    "message" : "Unknown resource '/dw/shop/v19_10/incognito'. Please provide a valid resource.",
    "arguments" : 
      {
         "path" : 
         {
            "type" : "string",
            "value" : "/dw/shop/v19_10/incognito"
         }
      }
  }
}
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:SS.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:SS.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.

400 (Bad Request)

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' is not 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.
InvalidShippingMethodException 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' is not 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' is not supported/activated for this site.
UsernameAlreadyInUseException Username is already in use.

401 (Unauthorized)

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

403 (Forbidden)

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

404 (Not Found)

Fault type Sample fault message
InvalidVersionException Invalid version syntax 'v19_10'. Please provide a valid version like 'v19_10'.
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 i.e. /dw/shop/v19_10/unknown/123.
UnknownVersionException Unknown version 'v33.33'. Please provide a valid version.

405 (Method Not Allowed)

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

406 (Not Acceptable)

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

413 (Request Entity Too Large)

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

414 (Request URI Too Long)

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

415 (Unsupported Media Type)

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

500 (Internal Server Error)

Fault type Sample fault message
InternalErrorException Internal Server Error.