Introduction

Custom APIs are becoming increasingly important in Dynamics 365 development. To ensure that they meet the highest standards, it’s important to be able to send appropriate HTTP status codes in response to client requests.

Recently, a client asked me if it was possible to send specific HTTP status codes from a Custom API in Dataverse. After some research, I discovered that it is indeed possible, and it’s a good practice to implement. In this article, I will explain the different ways to send appropriate HTTP status codes in a Custom API response, which can lead to a better user experience.

Problem

A Custom API may call an external service to fetch data, but sometimes, the service may return no records. To notify the user of the custom API that no records were found, it’s important to respond with the appropriate HTTP response code. In this case, the appropriate code is 404, indicating that the requested resource could not be found. Providing an accurate and descriptive response code can lead to a more efficient and satisfying user experience.

Solution

Basic Usage

When developing workflows and plugins in Dynamics 365, InvalidPluginExecutionException is commonly used to handle errors and exceptions. While this approach is suitable for simple scenarios, it may not provide enough flexibility for more complex situations.

The most basic way to use InvalidPluginExecutionException is to pass a string containing the error message to the constructor, like this:

throw new InvalidPluginExecutionException("An error occurred.")

1	throw new InvalidPluginExecutionException("An error occurred.")

This will throw an exception with the specified error message.

Overloads

In addition to the basic usage, there is an important overload of InvalidPluginExecutionException that allows you to pass a specific HTTP status code that you want to return from your custom API method.

The InvalidPluginExecutionException(String, PluginHttpStatusCode) overload takes two parameters:

The first parameter is a String that represents the error message you want to display to the user.
The second parameter is a PluginHttpStatusCode enumeration that represents the HTTP status code you want to return.

By using this overload, you can return specific HTTP status codes for different scenarios in your custom API. For example, if you want to notify the user that no records were found, you can use the code below to return a 404 status code.

throw new InvalidPluginExecutionException("No records found.", PluginHttpStatusCode.NotFound)

1	throw new InvalidPluginExecutionException("No records found.", PluginHttpStatusCode.NotFound)

Example with Not Found response

Here’s an example of a custom API that fetches data from an external system. If the query returns no results, the code will throw an InvalidPluginExecutionException with the message “No records found in System X” and a status code of 404. This will cause the API to return a 404 error to the user.

public class GetRecordsFromExternalSystem : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        // Fetch Records from external system
        var records = GetRecordsFromExternalSystem();

        if (records.Count == 0)
        {
            throw new InvalidPluginExecutionException("No records found in System X", PluginHttpStatusCode.NotFound);
        }
    }
}

public class GetRecordsFromExternalSystem : IPlugin

{

public void Execute(IServiceProvider serviceProvider)

{

// Fetch Records from external system

var records = GetRecordsFromExternalSystem();

if (records.Count == 0)

{

throw new InvalidPluginExecutionException("No records found in System X", PluginHttpStatusCode.NotFound);

}

HTTP Response of Custom API

When making a call to the upper API in Postman, for example, you will receive a 404 HTTP code if there is an issue with the request. In the response body, the message you sent in the string parameter will be included.

As an example, a properly formatted response could look like the following:

{
    "error": {
        "code": "0x80048d0a",
        "message": "No records found in System X"
    }
}

{

"error": {

"code": "0x80048d0a",

"message": "No records found in System X"

}

The user can easily identify the specific error that occurred and the associated error code. This information is critical in troubleshooting the issue and finding a resolution.

Conclusion

In conclusion, when developing custom APIs in Dynamics 365, it’s important to handle errors and exceptions properly. While the InvalidPluginExecutionException is a common approach to handling exceptions, it may not provide enough flexibility for more complex scenarios. By using the overload of InvalidPluginExecutionException that allows you to specify a specific HTTP status code, you can return appropriate HTTP response codes for different scenarios, such as when no records are found. This can improve the user experience and help with troubleshooting and debugging.

Dynamics Ninja

How to get most of your CRM platform

Using HTTP Status Codes to Improve Your Custom APIs