Introduction

Commonly a server indicates the result of REST request processing by responding different HTTP status codes. This behavior is not sufficient for REST clients that interact with an end user in most cases. Therefore there should be a coherent approach to how additional information about causes of errors or server-side business logic decisions should be provided to a REST client.

Glossary

Error Messages

The REST-based storefront requires an error handling that is more sophisticated than providing only HTTP status codes:

• Responding multiple failures as a result of a single request, e. g., basket validation failing for different reasons.
• Addressing several attributes contained in the request's payload that have wrong values, e. g., if invalid values for firstName and zipCode have been provided in the context of a single address update request.
• Providing invalid values together with valid limits or other information in the error message, e. g. value 4 is wrong; acceptable values: 5 to 10.

Those requirements cannot be met by a single HTTP response status code. Therefore any error message should provide the following information:

• status - [optional] The HTTP status code applicable to this problem.
• code - [mandatory] A unique identifier for this particular occurrence of the problem that may be used for localization on client side.
• message - [mandatory] Human readable message in the locale contained in the request. The server may fall back to providing a message in its lead locale if the requested locale is not supported.
• causes - [optional] An array of several other errors that caused the main one.
• parameters - [optional] Several parameters that are used to assemble the message or which give further information to the client.
• paths -  [optional] An array of JSON Path(s) [JsonPath] to the associated entity in the request document. If there is more than one path, then there is a relationship among the entities addressed by these paths, e. g., if the values specified for postal code and city do not match.

{
    "data": [],
    "errors": [
        {
            "status": "422",
            "code": "basket.add_line_item_not_successful.error",
            "message": "The product could not be added to your cart.",
            "causes": [
                {
                    "code": "basket.line_item.add_item_max_item_quantity_exceeded.error",
                    "message": "The product quantity for this item in your shopping cart has exceeded our Maximum Purchasing Policy.",
                    "parameters": {
                        "sku": "4852562"
                    }
                }
            ],
            "paths": [
                "$[0]"
            ]
        }
    ]
}

Info Messages

Besides information about errors there are other use cases for providing information about the processing of the request to a REST client. This functionality is mainly required by REST API for process-driven functionalities like basket handling, checkout and payment. The structure for info messages is similar to error messages.

Example: The user changes the quantity of a basket item from a value equal to 1 to 99. The REST-based storefront publishes this change via a PATCH request to the server. The server processes the request successfully, but adjusts the item's quantity finally to a value equal to 50, because this value is configured as maximum quantity for an item. The REST-based client has to inform the user about the adjustment.

{
    "data": {
        // ...
        "quantity" : 50,
        // ...
    },
    "infos": [
        {
            "code": "basket.line_item.update.info",
            "message": "The line item could not or only partially be updated."
            "causes": [
                {
                    "code": "basket.line_item.update_item_max_item_quantity_exceeded.info",
                    "message": "The quantity you entered is invalid. We have adjusted the quantity to meet our Maximum Purchasing Policy.",
                    "parameters": {
                        "requested": "99",
                        "lineItemId": "qdYKAEsBenwAAAFunNkvHJKP",
                        "granted": "50"
                    },
                    "paths": [
                        "$.quantity"
                    ]
                }
            ]
        }
    ],
}

Discussion

The following aspects have to be considered:

• Localization should be supported on server side (message) and client side (code, parameters) as well.
• There is no need to inform the client in case the server provides the message in the lead locale if the locale requested by the client is not supported by the server.
• Currently there is no special format/description language for parameters. However, the parameters should be described in the API reference documentation, because they are part of the API.