Dataverse Web API Tip #11: Extra Error Details

,

By default, a Dataverse Web API error message contains two fields, code and message. However, some errors have extra details available just for the asking.

Below, an OData annotations preference request is used to ask for additional error details. The request’s syntax is simple: include odata.include-annotations="{comma-separated list of requested annotations}" in the Prefer header.

GET {{webApiUrl}}SomethingThatCausesAnError
Prefer: odata.include-annotations="*" 
(include the "always include" headers)

(Above, a wildcard is used to request all annotations. It may be best to only use a wildcard like this only temporarily, during development. Once the specific annotations of interest have been identified, change the request to be more specific. This avoids the cost of unnecessary extra data being assembled and sent across the wire.)

Response:

{
  "error": {
    "code": "0x80048d08",
    "message": "Example Error Message.",
    "@Microsoft.PowerApps.CDS.ErrorDetails.OperationStatus": "0", 
    "@Microsoft.PowerApps.CDS.ErrorDetails.SubErrorCode": "10001",
    "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80048d08&client=platform",
    "@Microsoft.PowerApps.CDS.TraceText": "\r\n[Plugin: Plugin.Plugin]\r\n[03ded7cb-60a7-eb11-c2ac-010d4d3c26cd: My Plugin Step Name]\r\n\r\n\t\r\n\tGetting ready to do something.\r\n\t\r\n",,
    "@Microsoft.PowerApps.CDS.InnerError.Message": "Example Error Message."
  }
}

Be aware that error annotations are not necessarily intended for end-user or public consumption. The component raising the error may expect that these values will only be used for development and technical troubleshooting purposes and so may include content that is not end-user friendly or even that contains sensitive data. It is a good practice not to expose these extra error details publicly except when you are sure that the component raising the error will only return “safe to display” values.

Bonus Tip: If you’re writing a custom plugin, InvalidPluginExecutionException‘s first three arguments correspond to the OperationStatus, SubErrorCode and InnerError.Message annotations. Additionally, annotation TraceText will include any trace text written by the plugin, a fact that can be leveraged to include a full stack trace, if desired. Unfortunately, HelpLink is auto-set by Microsoft; I’m not aware of a way to set or override it.

Note

Don’t forget to include the “always include” headers with every request sent to the Web API.

Reference/Further Reading

Parse errors from the response (in Compose HTTP requests and handle errors)

Leave a Reply

Your email address will not be published. Required fields are marked *