Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.


The preferred means for surfacing errors to callers is to throw strongly typed exceptions from your business logic , and to register error handlers that turn the results into meaningful HTTP response messages.


This is what the stock eBusiness e-Business process components are doing. You will find documentation about what exceptions are thrown in the .NET documentation for the specific process components. 

All uncaught exceptions are translated into a JSON object with the following properties:

  • type Type - The kind of error that was generated. Typically it is the class name of the exception with the word 'Exception' removed. If the business logic throws an OrdersException then type will be 'Orders'. If it throws an ArgumentException the type is 'Argument'. If it throws a SecurityRequirementFailedException the type is 'SecurityRequirementFailed'. Both errorCode and Type are required to completely identify the error.
  • errorCode ErrorCode - a numeric identifier that further describes the error. Within each type, there are numeric codes that have explicit meanings. For example, the type of 'Order' can have errors codes of
    • 401 – add product failed because it is not a meeting product
    • 411 – add product failed because the product is not sold
    • 450 – no inventory is available for the product and backorder is not allowed
    • 400 – an unknown error occurred during add product
    • 700 – an unknown error occurred attempting to create payment information

Both errorCode and Type are required to completely identify the error. Numeric error codes can be reused for different types. The type 'ShoppingCart' could define an errorCode 700 that means 'invalid coupon code'.

  • message Message - a string message that tells us what the problem is. This is almost always the exception's message property.
  • responseIdentifier ResponseIdentifier - a server generated GUID that can be found in event viewer on the services web server to find more information about the error.  This can be used for troubleshooting.  If you are getting a response with no message, event viewer should have the full exception logged with the guidguide

Old end points endpoints do not conform to this standard yet. If you browse the help page for your services site, any end points endpoints that start with 'A{something}' are the old style of end pointsendpoints.

New end points endpoints that fail model validation do not conform to this standard yet. Model validation would be any input restrictions you see in the online end point endpoint help documentation, like fields that are required but not sent by the client. We will be updating model validation to this format before release.

In addition to the JSON object on the response body, an HTTP status code must be assigned to the response.  The framework will blank out the message property on the JSON object for any HTTP status codes >= 500.  These are considered internal server errors and the assumption is the message property may contain sensitive information that is not appropriate for end users to see.  HTTP status codes >= 400 and < 500 are assumed to be client facing messages and the message property will be populated.  Regardless the entire exception is always written to the Aptify Exception Manager.  


Notice that the HTTP status code is 400 Bad Request and the errorCode is zero.  You can then take the responseIdentifier value and search for it in Event Viewer on the web server running services to find additional details.  

How do I know what errorCode value


is available for a particular exception type?

By looking at the .NET documentation for the assembly that defines the exception.  You will see a class named ErrorCodes that lists them all out.  For example, the ShoppingCartInterfaces assembly defines the ShoppingCartException class.  This assembly also has an ErrorCodes class that lists out the possible error code values.  Similarly, the AptifyOrdersEntity assembly defines the OrdersException class.  This assembly also has a new ErrorCodes class that lists out the possible values and their meaning.