Introducing Dynamic Error Messages in SDKs

By default, APIMatic generated SDKs throw a generic error response on every failed API call. Now, you can customize these error responses by providing placeholders that populate at runtime.

Details

Previously, every time an API called failed, APIMatic SDKs surfaced a string response that was generic to all error responses in all languages. This error response provided little information on why the called failed so users had to manually dig into the response to find out the details. To facilitate the users, our SDKs already support Custom Error Messages that let users customize a static message against an HTTP error code. This adds more information as to why a call failed.

What Has Changed?

While Custom Error Messages support customizing error responses, there was still no way to provide any information from the exception at runtime. For this reason, we have introduced Dynamic Error Messages that allow users to define templated placeholders that get populated at runtime.

To configure this feature, you can use our OAS extensions in your OpenAPI specification file at either endpoint level or globally.

// At endpoint level
"/books": {
    "post": {
        ...
        "responses": {
            "400": {
                "description": "API call failed due to bad request."
            }
        },
        "x-operation-settings": {
            "errorTemplate": {
                "401": "API call failed with {$statusCode} - {$response.body#/details}.",
                "403": "API call failed of category - {$reponse.body#/category}.",
                "0": "API call failed because {$response.body#/details}." 
            }
        }
    }
}
// Globally for all endpoints
"x-codegen-settings": {
    "errorTemplate": {
        "404": "API call failed of content type - {$response.header.Content-Type}"
    }
}

Once the OpenAPI file has been configured, you can catch the exception while making the API call.

try
{
    booksController.CreateBook(book);
}
catch (ApiException exception)
{
    // Printing the error message
    Console.WriteLine(exception.Message);
}

Now, whenever an API call fails, you will get the dynamically configured error messages. For example, in case of error 403, SDK will surface the following error response:

API called failed of category AUTHENTICATION_ERROR.

For more details on Dynamic Error Messages, please refer to our feature documentation.