iThenticateDeveloperWebsite

Error Processing

XML-RPC is an HTTP-based protocol, and thus any client applications must look at the HTTP status code before attempting to parse the XML response. iThenticate API requests return 200 HTTP status code unless there is a serious error that prevents processing of the request. For example, attempting to contact the API with an invalid XML-RPC endpoint URL will result in a HTTP status code 404. Malformed XML-RPC requests (e.g. invalid XML) will likely generate a 500 HTTP status code.

The iThenticate XML-RPC response will include an api_status element that indicates the success or failure of the API request. The api_status for normal successful methods will be 200. Although the api_status code is similar to canonical HTTP responses code, they should not be considered the same. Differences between values for api_status and standardized HTTP response codes in the HTTP may be subtle and the user should remember that HTTP status codes and api_status are separate entities and will almost always have different values for responses. Clients should check the HTTP response code before looking at the api_status value returned in the XML-RPC response.

An api_status code of 401 is returned for authorization failures. This can be due to invalid login credentials or a request coming from an IP address not authorized for API requests.

An api_status code of 403 indicates that the user does not have access to the requested resource

An api_status code of 404 indicates that an object id in the response does not exist or is invali

An api_status code of 500 indicates that the request was invalid in some way. This would typically be if the data passed in the XML-RPC request did not meet the requirements of the method. For example, not providing required elements in the XML-RPC request or submitting incorrectly formatted data.

Additional information about an error can be obtained by inspecting two additional elements other than the api_status element.

As described above, the XML-RPC response may include a messages element. This element may provide an overall reason for the failure, for example “Failed to log in”, or a specific failure condition not covered by the errors field.

The distinction between the errors and the messages elements may not be entirely clear to the end user. In the case where the documentation is unclear, the user is advised to discern the exact behavior of each element from the response given by the API web service itself.

Example of a response that includes an error condition with a explanation in the messages element:

The message list may contain more than one message. For example, in this case more detail is provided about the error condition:

iThenticate API requests require one or more parameters. For example, logging in requires two parameters: a username and a password. The errors element, if included in the XML-RPC response, will provide details about errors with these parameters. The errors element is an XML-RPC struct element with the keys being the names of the parameters, and the values an XML-RPC list of one or more messages related to that parameter. The messages element may also contain details about errors encountered during the login process.

An example of the login method above shows an XML-RPC response where an invalid password parameter was submitted.

The following example shows an XML-RPC response that includes two messages, One begins with a generic message saying login did not succeed, and another message gives the reason for the failed login attempt.