Internal API-Guide

Download As PDF

Error Handling

The API calls return error data that your client application can use to identify and resolve runtime errors. If an error occurs during the invocation of most API calls, then the API provides the following types of error handling:

For errors resulting from badly formed messages, failed authentication, or similar problems, the API returns a fault message with an associated Exception Code.

For most calls, if the error occurs because of a problem specific to the query, the API returns an Error.

Exception Handling

What happens if a WebAPI controller throws an uncaught exception? By default, most exceptions are translated into an HTTP response with status code 500, Internal Server Error. The HttpResponseException type is a special case. This exception returns any HTTP status code that you specify in the exception constructor. For example, the following method returns 404, Not Found, if the id parameter is not valid.

Sample:
public Product GetProduct(int id)
{
  Product item = repository.Get(id);
  if (item == null)
  {
    throw new HttpResponseException(HttpStatusCode.NotFound);
  }
return item;
}

In case of failure, the controller methods throw an HttpResponseException exception with the appropriate error message, which allows for a given HttpResponseMessage to be returned to the internal.

API Fault Elements in Common Authorization

Fault Description
UNAUTHORIZED_MESSAGE Please provide valid inputs for authentication token, calling client and acting domain.
UNAUTHORIZED_MAX_CALLS_MESSAGE You have reached the max number of calls permitted by day.
NO_AUTH_REPO No valid authorization provider could be validated for this request.

API Fault Elements in Comments

Fault Description
NO_WO_NUMBER_OR_ID The requested action requires a work order number or id.
NO_COMMENT_SUPPLIED No comment was included to the request. A comment is required for this operation.
INSERT_COMMENT_ERROR Error, one or more comments were not saved correctly.

API Fault Elements of BaseApi

Fault Description
FILTER_ERROR The provided filtering criteria is invalid. Please provide a valid one.
AUTHENTICATION_ERROR The provided authentication/authorization header information is incorrect, please proceed to verify it.
INVALID_INTERNALFILTER Invalid internal filter (CompoundFilterDTO).

API Fault Elements of IFMBridge

Fault Description
RULE_FAILED_NO_MESSAGE Business rules failed, but no message was received. Rules response code:
WORKORDER_NOT_FOUND WorkOrder matching the Id or Number was not found.
VENDOR_NOT_IN_WHITELIST WorkOrder vendor was not in the whitelist.
CLIENT_NOT_FOUND Client matching the Id was not found.
SOURCE_STATUS_DOESNT_MATCH Source({0}) workorder {1} is in status {2} not in status {3}, so the linked workorder may not be updated.

API Fault Elements in Markup

Fault Description
NO_WO_NUMBER_OR_ID The requested action requires a work order number or id.
INVALID_WO_NUMBER_OR_ID The provided Work Order ID or Number doesn't match with a valid Work Order.
INVALID_STATUS The current Work Order Status '{0}' is invalid.

API Fault Elements in Pricing

Fault Description
RATE_TYPE_CANNOT_BE_EMPTY Please provide a valid Rate Type.
RATE_KIND_CANNOT_BE_EMPTY Please provide a valid Rate Kind.
RATE_OPTION_CANNOT_BE_EMPTY Please provide a valid Rate Option.

API Fault Elements in Quotes

Fault Description
NO_WO_NUMBER_OR_ID The requested action requires a work order number or id.
QUOTE_NOT_FOUND No quotes could be found for the supplied Work Order.

API Fault Elements in WorkOrders

Fault Description
NO_WO_NUMBER_OR_ID The requested action requires a work order number or id.

API Fault Elements in IFMRequestMappingXML

Fault Description
UNABLE_MAP_REQUEST Unable to find mapped request code and request type.