internal/functions/batch/Write-EntraItemFailure.ps1

function Write-EntraItemFailure {
    <#
    .SYNOPSIS
        Reports an input item that could not be processed: ONE non-terminating error for it.

    .DESCRIPTION
        A cmdlet that takes many input items (pipeline, an array parameter) reports each one that failed as ONE error
        record - its target object is the caller's input object, so -ErrorAction and -ErrorVariable work per item - and
        goes on with the others. There is no warning per item: the run's one summary (Write-EntraBatchSummary) counts
        them. An item reported once in a run is not reported again (a key whose second page failed is still one item).
        With -EnableException no record is written here; the cmdlet throws at the end of the run.
        The reason is cleaned before it is shown: a URL loses its query (skip and delta tokens), a bearer token its
        value. The category follows the status: 401/403 PermissionDenied, 404 ObjectNotFound, 400/405/422
        InvalidArgument, 421 SecurityError, 429 LimitsExceeded, another status or none ConnectionError, unless
        -Category names one.

    .PARAMETER Cmdlet
        The $PSCmdlet of the public cmdlet; the error is written in its name.

    .PARAMETER Report
        The run's report.

    .PARAMETER Target
        The caller's input object.

    .PARAMETER Label
        What failed, for the message and the summary: an id or a name. Never a link or a token.

    .PARAMETER Status
        The HTTP status of the failure, 0 when there is none.

    .PARAMETER Reason
        The failure message; it is cleaned of queries and tokens.

    .PARAMETER Category
        The error category, instead of the one the status gives.

    .PARAMETER ErrorId
        The FullyQualifiedErrorId of the record.

    .PARAMETER EnableException
        Record only; the cmdlet throws at the end of the run.

    .EXAMPLE
        PS C:\> Write-EntraItemFailure -Cmdlet $PSCmdlet -Report $report -Target $group -Label $group.Id -Status $page.Status -Reason $page.Error

        Writes one error for the group and counts it for the summary.
    #>

    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCmdlet]
        $Cmdlet,

        [Parameter(Mandatory = $true)]
        [hashtable]
        $Report,

        [AllowNull()]
        [object]
        $Target,

        [Parameter(Mandatory = $true)]
        [string]
        $Label,

        [int]
        $Status,

        [AllowEmptyString()]
        [AllowNull()]
        [string]
        $Reason,

        [System.Management.Automation.ErrorCategory]
        $Category,

        [string]
        $ErrorId = 'PSMicrosoftEntraID_ItemFailed',

        [bool]
        $EnableException
    )

    if (-not $Report.ContainsKey('Items.Reported')) { $Report['Items.Reported'] = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase) }
    # One record per input item and run.
    if (-not $Report['Items.Reported'].Add($Label)) { return }

    # No query of a link (skip and delta tokens) and no bearer token in a message.
    [string] $text = [string]$Reason
    $text = [regex]::Replace($text, '(https?://[^\s?#"'']+)[?#][^\s"'']*', '$1')
    $text = [regex]::Replace($text, '(?i)(bearer\s+)[A-Za-z0-9\-\._~\+/]+=*', '$1***')

    if (-not $PSBoundParameters.ContainsKey('Category')) {
        $Category = switch ($Status) {
            { $_ -in 401, 403 } { 'PermissionDenied'; break }
            404 { 'ObjectNotFound'; break }
            { $_ -in 400, 405, 422 } { 'InvalidArgument'; break }
            421 { 'SecurityError'; break }
            429 { 'LimitsExceeded'; break }
            default { 'ConnectionError' }
        }
    }
    [string] $message = if ($Status) { (Get-PSFLocalizedString -Module 'PSMicrosoftEntraID' -Name 'Batch.ItemFailed') -f $Label, $Status, $text }
    else { (Get-PSFLocalizedString -Module 'PSMicrosoftEntraID' -Name 'Batch.ItemFailed.NoStatus') -f $Label, $text }
    Write-PSFMessage -Level Debug -Message $message -FunctionName $Cmdlet.MyInvocation.MyCommand.Name
    if ($EnableException) { return }
    $record = [System.Management.Automation.ErrorRecord]::new([System.Exception]::new($message), $ErrorId, $Category, $Target)
    $Cmdlet.WriteError($record)
}