nopSolutions/nopCommerce · error · NopException

Item HS classification error: {error}

Error message

Item HS classification error: {error}

What it means

Thrown when the deserialized HS classification response contains a non-empty result.Error.Code, meaning Avalara accepted and parsed the request but returned a structured application-level error. The message aggregates Error.Code plus any Details (each with Message and Description).

Source

Thrown at src/Plugins/Nop.Plugin.Tax.Avalara/Services/ItemClassificationHttpClient.cs:105

            //return result
            TResponse result = null;
            var responseString = await httpResponse.Content.ReadAsStringAsync();
            try
            {
                result = JsonConvert.DeserializeObject<TResponse>(responseString ?? string.Empty);
            }
            catch (Exception ex)
            {
                throw new NopException($"Item HS classification error: response content invalid - {ex.Message}");
            }
            if (!string.IsNullOrEmpty(result?.Error?.Code))
            {
                var error = result.Error.Code;
                if (result.Error.Details?.Any() ?? false)
                    error += result.Error.Details.Aggregate(string.Empty, (text, e) => $"{text}{e.Message} {e.Description};{Environment.NewLine}");

                throw new NopException($"Item HS classification error: {error}");
            }

            return result;
        }
        catch (AggregateException exception)
        {
            //rethrow actual exception
            throw exception.InnerException;
        }
    }

    #endregion
}

View on GitHub (pinned to 64bdf2ff08)

Solutions

  1. Read the aggregated error details (Code + each Detail Message/Description) from the exception message — they name the exact field/problem.
  2. Validate the CreateHSClassificationRequest payload (CountryOfDestination, Item fields) before sending.
  3. Confirm the Avalara subscription includes the HS classification service for the target country.

Example fix

// before
throw new NopException($"Item HS classification error: {error}");

// after — surface details as a typed record
throw new NopException($"Item HS classification error: {error.Code}", new HsClassificationApiException
{
    Code = error.Code,
    Details = error.Details?.Select(d => (d.Message, d.Description)).ToList()
});
Defensive patterns

Strategy: try-catch

Validate before calling

var missing = new[] { classificationModel.CountryOfDestination, classificationModel.Item?.Code }.Where(string.IsNullOrWhiteSpace).ToList();
if (missing.Any()) throw new NopException($"HS classification missing fields: {string.Join(",", missing)}");

Type guard

static bool IsValidClassificationRequest(CreateHSClassificationRequest r) => !string.IsNullOrWhiteSpace(r?.CountryOfDestination) && r?.Item is not null;

Try / catch

try { await client.RequestAsync<TReq,TResp>(request); }
catch (NopException ex) when (ex.Message.Contains("Item HS classification error"))
{ _logger.LogError(ex, "Avalara rejected HS classification: {Msg}", ex.Message); throw; }

Prevention

When it happens

Trigger: Avalara rejects the classification request at the business level: invalid company, invalid item payload, missing required fields (country of destination, product info), quota exceeded, or permission errors.

Common situations: CountryOfDestination is null/invalid; Item payload missing required product identifiers; the AccountId/LicenseKey pair is valid but lacks HS-classification scope; rate limit/quota hit.

Related errors

AI-assisted analysis of nopSolutions/nopCommerce@64bdf2ff08 (2026-08-13). Data as JSON: /api/errors/992c990700a39496. Report an issue: GitHub.