03_status-codes.md

Status codes

Every OTTO Retail-API call returns an HTTP status code to indicate success or failure of a request.

Success

For successful requests, the OTTO Retail-API returns the following HTTP status codes:

Status code	Description
200 OK	The HTTP request succeeded.
201 Created	A POST or PUT request successfully created a new resource. The response provides the URI of the new resource in the Location header.
202 Accepted	The API accepted the request and will process it asynchronously.
204 No Content	The server successfully fulfilled the requested operation, but does not return a response body.

Redirection

The OTTO Retail-API returns the following HTTP status codes when the availability or location of a resource has changed, or when a resource has not been updated.

Status code	Description
301 Moved Permanently	The resource is no longer available under the requested path. This and all future requests must be directed to the specified URI.
303 See Other	The response to a POST, PUT, PATCH, or DELETE request is available under another URI using a GET method.
304 Not Modified	The requested resource does not need to be resent. It is an implicit redirect to a cached resource. The resource has not been modified since the date or version passed via request headers If-Modified-Since or If-None-Match.
307 Temporary Redirect	The response to the request is temporarily available via another URI using the same method of the initial request.
308 Permanent Redirect	The response to the request is permanently available via another URI using the same method of the initial request.

Client error

In case of failed requests, the OTTO Retail-API returns the following HTTP status codes:

Status code	Description	Possible cause and solution
400 Bad Request	Request is malformed, syntactically incorrect or violates the schema.	The API was not able to validate the request. Possible causes for this condition: The API cannot convert the payload data to the underlying data type, or the data is not in the expected data format or does not contain all required properties.
401 Unauthorized	User authentication failed.	The request requires a valid user authentication. Either the request header does not provide an access token or the access token has expired and needs to be refreshed.
403 Forbidden	Request is valid but does not have sufficient rights.	The API refuses access to the requested resource most likely due to insufficient rights. Re-authenticating does not solve this. A possible cause is an incorrect value of the scope property of the access token.
404 Not Found	The requested resource does not exist.	Possible causes for a 404 status code are a malformed query structure or a misspelled name of the requested resource.
405 Method Not Allowed	The API endpoint does not support the requested HTTP method.	The API does not support the requested method for the target resource. This status occurs, for example, after sending a POST or PUT request to a read-only resource. The supported methods are available in the endpoint documentation.
406 Not Acceptable	The API does not support the requested media type.	The API cannot use the requested media type to return the response payload. This error might occur, for example, if the client sends an Accept: application/xml request header, but the API can only generate an application/json response. Possible causes can be a request targeting an outdated API version or media type.
409 Conflict	The API cannot complete the request due to a conflict with the current state of the resource.	An update operation for a resource fails because the resource already was updated since it was retrieved by the client. A possible cause for this response is, when a client requests the same action for the same resource on two different registered devices.
410 Gone	The requested resource is no longer available.	A possible cause for this status response is a malformed request structure.
412 Precondition Failed	The precondition defined by the request failed.	The API denies access to the target resource, for example, if an edit conflict between multiple simultaneous updates occurs. This might also appear if the If-Match header does not match the resource's ETag.
413 Payload Too Large	The request payload exceeds the limit of the API.	The request header or body exceeds the defined limit. This might happen for requests with a large JWT containing many scopes or a large HTTP body.
415 Unsupported Media Type	The API does not support the media type of the request payload.	The API refuses to accept the PUT, PATCH, or DELETE request because the payload format is not supported or malformed. Ensure your request body contains a content type and is syntactically and semantically correct.
422 Unprocessable Entity	The API cannot complete the requested action.	Indicates a logically invalid request body. The server understands the content type of the request entity and the syntax is correct. However, the server was unable to process the contained instructions, for example, due to semantically incorrect data such as a date of birth that lies in the future.
428 Precondition Required	The API requires the request to be conditional.	The API requires the request to include a precondition header, such as If-Unmodified-Since or If-Match. Without this header, the API cannot determine if the client has the same version of the resource. To resolve this condition, first find out the current version of the resource by sending a GET or HEAD request, and then reading either the E-tag or Last-Modified headers. Finally, add this information as a precondition header to the next update request.
429 Too Many Requests	Too many requests. Blocked due to rate limiting.	The client has sent too many requests in a given time. Make sure that your implementation provides a rate limit for the requests. Our API allows a daily rate of 100,000 requests.

Server error

For server-side errors, the OTTO Retail-API returns the following status codes:

Status code	Description
500 Internal Server Error	The server encountered an unexpected condition that prevents fulfilling the request.
501 Not Implemented	The server does not support the functionality required to fulfill the request.
503 Service Unavailable	The server is (temporarily) not able to handle the request.