Error Reports

Error Reporting: a human+machine-friendly aspect

Motivation

   Proper formal error reporting is essential for helping services understand the reason something went wrong and take proper actions. The main issues encountered so far are summarized as follows:

• HTTP status codes have been proved ambiguous and do not provide enough information to the client. A status code 400 (Client Error, Bad request) tells the client that there was something wrong with the
  request and it should not be repeated but provides no information about the error itself.
• The status code 502 tells the client that is received an error while acting as a client (or proxy) but does not reproduce the error it received, nor tells which is the remote server that threw the error. So a 502 might mask
  a 400, 404, 500, or any other kind of error.
  
• Explanatory messages may be included in the body of the response providing information about the exception. On the one hand this human-readable report facilitates the debugging and provides valuable information
  to the developers but is not much help towards automating subsequent actions (its not easily machine-readable).
  

Requirements

Taking these into account we conclude that there is a need for an error reporting API meeting the following requirements:

• Error reporting should be machine readable and include all details needed to understand what exactly went wrong.
• Human readable messages should be available as well.
  
• Services that receive an error report should replicate it, that is provide a new error report including the information they received from the remote service. The
  status code in that case should be 502, but the error report will provide the details needed.
• Error reports should be available in both plain text and RDF/XML format. The latter (rdf) is intended to be used as a machine readable object thus should be properly documented/specified in the API.

First steps

The first question to be addressed is what information should  an error report contain and how could these be provided in a structured way to meet the requirements stated above. So, an error report should contain at least the following information:

1. The error code: An element of a standard enumeration. The error code can be identified by a simple keyword or an integer (eg. NoSuchFeatureInDataset  or 121 ).
   
2. URI of the service: The URI of the service throwing the exception
3. Message: An brief explanatory message for the error code (e.g. "the prediction feature you provided is not included in the training dataset" )
4. Details: Details about the error message. If the error was caused by the some bad request or bad input data a hint can be provided to the client. For example if the client provided the tuning parameter gamma=-1 while
   gamma should be positive, a hint can be something like "The value you provided for the parameter gamma is negative while it accepts only positive values".
5. Cause: Another error report. If the service was acting as a client and received an error report it should include the error report it received.
   

An RDF representation of the error report can be easily obtained by a proper extension of the API.

Error Report in RDF

 Here are some examples of how an error report may look like:

• A client invokes a model training service providing a dataset uri and a prediction feature not included in that set:
  

  x a ot:ErrorReport;
    ot:errorCode err:PredictionFeatureNotInDataset;
    ot:actor <http://opentox.ntua.gr:3000/algorithm/svm>;
    ot:message "The prediction feature you provided is not contained in the dataset"^^xsd:string;
    ot:errorDetails "The prediction feature you provided (http://someserver.com/feature/100) is not contained 
                     in the dataset. Available features are:
                     ** List of features goes here **"^^xsd:string .
  

• A model training service receives an acceptable request but receives an error from the feature service while trying to create the prediction feature
  

  x a ot:ErrorReport;
    ot:errorCode err:CannotGeneratePredictrionFeature;
    ot:actor <http://opentox.ntua.gr:3000/algorithm/svm>;
    ot:message "An error was received from the feature service and the prediction feature could not be created";
    ot:errorDetails "The remote server at http://some.opentox_server.net/feature"^^xsd:string;
    ot:errorCause y .
  y a ot:ErrorReport;
    ot:errorCode err:ServiceUnavailable;
    ot:actor <http://some.opentox_server.net/feature>;
    ot:message "The service is temporarily unavailable. Please try again after 10 minutes"^^xsd:string .
  

• Consider the case where there exist multiple feature services. Let A be a model training service and B and C two feature services. The service A posts a feature to the service B and receives an error. Then attempts
  to post the feature to service C. If the request succeeds, then the error received from service B is omitted. But if both requests fail then the error report returned to the client should include the error reports produced by
  both remote services B and C. Here is an example of such a representation:
  

  x a ot:ErrorReport;
    ot:errorCode err:CannotGeneratePredictrionFeature;
    ot:actor <http://opentox.ntua.gr:3000/algorithm/svm>;
    ot:message "An error was received from the feature service and the prediction feature could not be created";
    ot:errorDetails "The remote server at http://some.opentox_server_A.net/feature"^^xsd:string;
    ot:errorCause [y z] .
  y a ot:ErrorReport;
    ot:errorCode err:ServiceUnavailable;
    ot:actor <http://some.opentox_server_A.net/feature>;
    ot:message "The service is temporarily unavailable. Please try again after 10 minutes"^^xsd:string .
  z a ot:ErrorReport;
    ot:errorCode err:NotAFeatureRepresentation;
    ot:actor <http://some.opentox_server_B.net/feature>;
    ot:message "The RDF representation you posted is not recognized as the representation of a feature"^^xsd:string 
    ot:details "The posted RDF is syntactically correct but no feature resource was found in it."^^xsd:string.
  

An hierarchical structure can be also adopted for the error codes. For example:

err:NotAFeatureRepresentation rdf:subclassOf err:ImproperRDFRepresentation
err:ImproperRDFRepresentation rdf:subclassOf err:BadRDFContent
err:BadRDFContent rdf:subclassOf err:SomeOtherException

Current Challenges

. These should be followed by a corresponding HTTP status code and a brief explanation. For example:

References/Links

1. Restful Error Handling (A must-read article)
   
2. Exception Handling in Web Services [Article from developer.com]
3. Handling and Throwing Exceptions in XML Web Services
4. Exception Handling and Recovery of Semantic Web Service