Recommended way to identify Native Authentication error responses

Question

Recommended way to identify Native Authentication error responses

Amanda 0

Hi,

I'm evaluating Microsoft Entra External ID Native Authentication and have been testing the error responses returned by the Sign Up, Sign In, Password Reset, and Refresh Token flows.

During my testing, I observed that error responses consistently contain:

error
error_codes (array)
sometimes suberror

For example:

{

"error": "invalid_grant",

"error_codes": [50181],

"suberror": "invalid_oob_value"

}

I also noticed that the error field is not unique. Different failure scenarios may return the same value (for example, invalid_request `or invalid_grant), while the values in ``error_codes appear to uniquely identify the failure.

However, the documentation states:

"Error codes are subject to change at any time and should never be used by the client itself."

I have a few questions:

Is ``error_codes` the recommended field for distinguishing Native Authentication error conditions?
Although error_codes is defined as an array, all the responses I observed contained exactly one value. Can multiple error codes be returned? If so, under which circumstances?
If multiple error codes can be returned, is there a documented way to interpret them (for example, is their order significant)?
Is there another stable field that Microsoft recommends using to identify specific Native Authentication error conditions?

I couldn't find guidance on this in the documentation, so any clarification would be appreciated.

Thank you.

0 comments

1 answer

Your answer

Answer 1

The documented fields intended for client handling are error and, when present, suberror.

From the Native Authentication API reference:

error is described as an error code string that can be used to classify types of errors and react to errors.
suberror is described as an error code string that can be used to further classify types of errors.
error_codes is described as a list of Microsoft Entra-specific error codes that can help diagnose errors.

Based on that:

error_codes is not the recommended field for client-side distinction of Native Authentication error conditions. The documentation explicitly positions it as diagnostic data, while error and suberror are the fields described for classification and reaction.
error_codes is defined as a list, but the provided documentation does not state when multiple values are returned or give any Native Authentication examples with more than one value.
There is no documented interpretation model in the provided material for multiple error_codes values. No ordering semantics or precedence rules are described.
The stable fields documented for identifying specific Native Authentication error conditions are:
- error for the primary category
- suberror for finer-grained classification when included

Examples from the documentation support this pattern:

Sign-up and sign-in flows list supported error values such as invalid_request, invalid_grant, invalid_client, expired_token, and others.
Several flows state that when error is invalid_grant, Microsoft Entra includes suberror to indicate the exact cause.
In SSPR, invalid_grant can be refined by suberror such as invalid_oob_value.

A practical interpretation from the documented contract is:

Use error first to branch by broad failure type.
Use suberror when present to distinguish specific causes within that failure type.
Treat error_codes, trace_id, correlation_id, and timestamp as diagnostics and support/troubleshooting data rather than application control signals.

The provided documentation does not contain a documented recommendation beyond that.