OCAPI HTTP Status Codes and Faults

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

Fault Document

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

1{
2  "fault": {
3    "type": "NotFoundException",
4    "message": "Unknown resource '/dw/shop/v24_5/incognito'. Please provide a valid resource.",
5    "arguments": {
6      "path": {
7        "type": "string",
8        "value": "/dw/shop/v24_5/incognito"
9      }
10    }
11  }
12}

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:24.500"}`

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

401 (Unauthorized)

Fault type	Sample fault message
`InvalidSecureTokenException`	Session may have been hijacked.
`UnauthorizedException`	Unauthorized request for resource ‘/s/SiteGenesis/dw/shop/v24_5/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’.

403 (Forbidden)

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

404 (Not Found)

Fault type	Sample fault message
`InvalidVersionException`	Invalid version syntax ‘v24.5’. Provide a valid version like ‘v24_5’.
`NotFoundException`	No product with id ‘0815’ for site ‘SiteGenesis’ found.
`ResourcePathNotFoundException`	If the requested URL matches the B2C Commerce Digital Rest URL pattern, but the resource path is unknown that is, /dw/shop/v24_5/unknown/123.
`UnknownVersionException`	Unknown version ‘v33.33’. 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.

Attention!

The Open Commerce API (OCAPI) is now deprecated. The provisions described in our versioning and deprecation policy fully apply. For all new projects and major refactoring work, use B2C Commerce API (SCAPI) as the default REST API. For additional details, refer to Why Use SCAPI Instead of OCAPI.

DID THIS ARTICLE SOLVE YOUR ISSUE?
Let us know so we can improve!