Typically, in the API specification, your only top-level error will be CommonErrorSpec.VALIDATION_ERROR. However, you can include error detail specifications that can appear under that top-level error.

The following is how the TemplateRenderAdapter defines the specification for the INVALID_ATTRIBUTE_NAME error detail.
public final static AuthnErrorDetailSpec INVALID_ATTRIBUTE_NAME = new AuthnErrorDetailSpec.Builder()
	.message("An invalid attribute name was provided.")

The error detail specification must reference the error code of its parent top-level error. This ensures that the authentication API Explorer correctly represents the error information.

INVALID_ATTRIBUTE_NAME is an example of an error that would be useful for API client developers but not for end users.

For more information about defining user-facing errors, see Error messages and localization.