Show TOC

Error Response Control for Backend Data ProviderLocate this document in the navigation structure

Use

The response of an OData request causing an error looks like this example:

Figure 1: Example

This error response contains the following artifacts:

  • Error code

    The T100 message class and number of the error message.

    In this example it is /IWBEP/CM_TEA/004.

  • Error message

    The text of the error message.

    In this example it is Team ID 'TEAM_012345678' is not in the defined range.

  • Transaction Id

    This ID identifies traces belonging to one transaction on all involved systems.

    In this example it is 4FDF3748112322F4E10000000A420C41.

  • One or several error detail entries which each contains:

    • Inner error code

      •The T100 message class and number of the error message or the name of the exception class that contributed this error. In this example it is /IWBEP/CM_TEA/004.

    • Inner error message

      The text of the error message.

      In this example it is Team ID 'TEAM_012345678' is not in the defined range.

    • Property reference

      The XPATH expression (entity type / property name) pointing to the corresponding property for this message if available. In this example it is Team/Team_Identifier or empty.

    • Severity

      Possible severities are info, warning and error. In this example it is error.

A backend data provider can control this error by the exception it raises and optionally also by adding messages to the message container of the raised exception.

To trigger an error a backend data provider application raises a business exception or a technical exception:

  • A business exception is class /IWBEP/CX_MGW_BUSI_EXCEPTION or a class inheriting from it.

  • A technical exception is class /IWBEP/CX_MGW_TECH_EXCEPTION or a class inheriting from it.

Each exception of the exception chain (provided by the previous exception when raising a business or technical exception) will be mapped to an error detail entry, as shown in the following example.

<errordetail>    
    <code>/IWBEP/CX_TEA_BUSINESS</code>
    <message>'TEAM_012345678' is not a valid ID.</message>    
    <propertyref/>    
    <severity>error</severity>
<target>ID</target>
</errordetail> 

One of these messages may be marked as the leading message. If a leading message is added to the message container its code and text will be used as the error code and error message of the error response.

Recommendation

We recommend using target. The target allows to relate a detail message to (a part of) an OData resource, or a related OData resource. This is especially needed for errors occuring during form field validation.

The target is always a relative resource path segment:

  • For GET, PATCH, PUT, and DELETE requests to a single entity or complex-type instance the target segment is either of the following:

    • Empty - if the error is related to the addressed resource as a whole, for example, a Sales Order.

    • A property path relative to the addressed resource, that is, if a forward slash and the value of target is appended to the path part of the request URL, the result is an OData request URL identifying the target of the error message.

  • For POST requests that create a new entity the target segment is relative to the Location response header that identifies the newly created resource, and otherwise follows the rules for GET, PATCH, PUT, and DELETE requests to a single entity.

  • For GET requests to a collection of entities the target segment starts with a key segment that identifies a single entity and is then optionally followed by a forward slash and a property path to address a specific part of the entity.

A backend data provider can also use the message container (interface /IWBEP/IF_MESSAGE_CONTAINER) to add one or several messages to the exception it raises.

Options

A backend data provider has several options of how to control the error response:

  • Exception only

    The backend data provider triggers an exception.

  • Exception with message container but without leading message

    The backend data provider triggers an exception where the message container contains one or several messages. Only messages with the attribute IS_LEADING_MESSAGE set to FALSE have been added to the message container.

  • Exception with message container with leading message

    The backend data provider triggers an exception where the message container contains one or several messages. At least one message with the attribute IS_LEADING_MESSAGE set to TRUE has been added to the message container.

Framework Behavior

Depending on the option chosen by the backend data provider the framework behaves as follows.

Exception Only

The text of the triggered exception is used as “Error Message". The exception is also shown as an error detail. If there is an exception chain (the exception referencing another exception via PREVIOUS (that is referencing another exception… that is …) each exception of the exception chain is shown as an error detail. Note that if an exception might contain sensitive or too technical information it should not be added via PREVIOUS. The inner error code of an exception is the name of the exception class that contributed this error.

Exception Containing the Message Container but Without Leading Message

The error message and the error details are filled the same way as in the case “Exception only”. Additionally, every message of the message container is added as an error detail. The inner error code of the message from the message container is the T100 message class and number of that message. These messages can have severity info, warning or error.

Exception Containing the Message Container With a Leading Message

The leading message of the message container is used as the error message. All exceptions of the exceptions of the exception chain are shown as error details. Additionally, every message of the message container is added as an error detail as described above. If there are no previous exceptions the exception itself is not shown in the error details.

Example of Error Response
<?xml version="1.0" encoding="utf-8"?>
<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
<code>SG/107</code>
<message xml:lang="en">Currency AZN is not defined</message>
<innererror>
<transactionid>5454F6F183877EC3E10000000A4C4325</transactionid>
<timestamp>20141107140000.0000000</timestamp>
<Error_Resolution>
<SAP_Transaction>Run transaction /IWFND/ERROR_LOG on SAP Gateway hub system and search for entries with the timestamp above for more details</SAP_Transaction>
<SAP_Note>See SAP Note 1797736 for error analysis (https://service.sap.com/sap/support/notes/1797736)</SAP_Note>
<Additional_SAP_Note>See SAP Note 1868586 (https://service.sap.com/sap/support/notes/1868586). This SAP Note contains application specific information.</Additional_SAP_Note>
</ErrorResolution>
<errordetails>
<errordetail>
<code>SG/107SG/107>
<message>Currency AZN is not defined</message>
<propertyref/>
<severity>error</severity>
<target>PricingTerms/CurrencyCodePricingTerms/CurrencyCode</target>
</errordetail>
<errordetail>
<code>SG/122</code>
<message>Exchange rate zero</message>
<propertyref/>
<severity>error</severity>
<target/>
</errordetail>
</errordetails>
</innererror>
</error>
 
More Information

A backend data provider can set the HTTP status code when raising a business or technical exception.

A backend data provider should log all messages relevant for error analysis but that are not relevant for an end user via the logger (class /IWBEP/CL_COS_LOGGER). This writes these logs into the Application Log and optionally also into the Computing Center Management System (CCMS).