Showing Custom Error Messages in MPOS from the Commerce Runtime

Three ways to surface a custom error message in MPOS, depending on where the error condition is detected.

From resources.json

MPOS's standard error handlers expect error strings in resources.json (en-US) in this format:

"string_55001": "This is a custom error."

Triggering it from MPOS directly

let displayMessageActivity: Commerce.Activities.DisplayMessageActivity =
    new Commerce.Activities.DisplayMessageActivity({
        title: 'Custom Error',
        message: Commerce.ViewModelAdapter.getResourceString("string_55001")
    });

displayMessageActivity.execute().done(() => {
    // code to run on successful display of the error dialog
}).fail(() => {
    // code to run on failure in displaying the error dialog
});

Triggering it from the Commerce Runtime

If the error condition is detected in the CRT instead, throw a CommerceException and let it surface in MPOS:

throw new CommerceException("string_55047", "CUSTOM ERROR MESSAGE");

Mapping third-party error codes

On one integration, a third-party application returned a fixed list of numeric error codes with their own messages — for example:

INVALID_OPTION = 152
ERROR_NEW_PASSWORD_CANNOT_BE_THE_SAME_AS_OLD_PASSWORD = 180

I mirrored those as a CRT enum:

public enum AppError
{
    INVALID_OPTION = 152,
    ERROR_NEW_PASSWORD_CANNOT_BE_THE_SAME_AS_OLD_PASSWORD = 180,
    // ...
}

Then, after deserializing the response, checked ReturnStatus and used a fixed offset (50050) to throw the matching resources.json string:

if (Enum.IsDefined(typeof(AppError), res.ReturnStatus))
{
    AppError err = (AppError)res.ReturnStatus;
    throw new CommerceException(
        "string_" + (50050 + res.ReturnStatus),
        err.ToString().Replace("_", " ")
    );
}

Update: there's a simpler way that avoids the resource-string mapping entirely — the Retail SDK sample shows setting LocalizedMessage directly:

throw new CommerceException("Microsoft_Dynamics_Commerce_30104", "Custom error")
{
    LocalizedMessage = "Custom error message returned by the third party app"
};