Handling Historical HTS Codes Without Inventing a Duty Rate

Archie Kane — Mon, 26 Oct 2026 15:49:47 +0000

Disclosure: I’m Archie Kane, Growth Lead at USTariffRates. This example was checked against the public API on October 26, 2026.

An old product catalog can contain a syntactically valid HTS code that is no longer in the current schedule. Treating it as a typo—or silently dropping the final two digits—can turn a useful validation failure into an unsupported duty quote.

Here is a real response and a small client-side pattern for handling it.

Reproduce the lookup

curl --include \
  'https://ustariffrates.com/api/v1/lookup?code=0901.21.00.35&country=brazil'

This request returned HTTP 404. Selected fields from the response:

{
  "error": "not_found",
  "hts": "0901.21.00.35",
  "hts_status": {
    "status": "historical_inactive",
    "hts": "0901.21.00.35",
    "current_schedule": false,
    "description": "Certified Organic",
    "removed_on": null,
    "removal_evidence": null,
    "archive_coverage": {
      "effective_from": "1989-01-01",
      "effective_to": "2019-02-15"
    }
  },
  "match_required": "exact",
  "valid_parent_line": {
    "hts": "0901.21.00",
    "description": "Not decaffeinated"
  },
  "message": "The requested statistical code is not in the current US HTS. The eight-digit parent line exists; verify the correct classification before requesting a duty result."
}

The full response linked archived official editions, including the 2018 HTSA Revision 14.1 edition, where the code was listed. It did not provide a supported removal date or a replacement statistical code.

Three distinctions matter:

Historical evidence is not current validity. A code appearing in an old official edition does not make it valid for a current entry.
Archive coverage is not a removal date. The end of the available archive window does not establish when this code ceased to apply.
A valid parent is not an automatic replacement. The parent describes a broader line. It is not permission to file or calculate under an inferred statistical suffix.

For a historical entry, verify the official schedule and applicable measures for that entry date. A current lookup failure does not, by itself, determine how a past entry should have been filed.

Branch on the diagnostic, not only the HTTP code

A 404 here has useful structured meaning. Preserve it rather than rendering “try again later” or replacing it with an empty rate object.

def classify_lookup_response(http_status, payload):
    if http_status == 429:
        return "rate_limited"
    if http_status in (401, 403):
        return "access_problem"
    if http_status >= 500:
        return "service_problem"
    if http_status == 404:
        status = (payload.get("hts_status") or {}).get("status")
        if status == "historical_inactive":
            return "classification_review_required"
        return "code_not_found"
    if not 200 <= http_status < 300:
        return "request_problem"
    return "inspect_duty_layers"

This helper routes responses; it does not validate a classification or approve a duty amount. Its branches were checked locally with fixture inputs. The historical-inactive example above came from the live API; the other branch inputs were synthetic checks, not claims that those errors occurred during this lookup.

A useful customer-facing state for this example is:

This code appears in historical HTS records but is not in the current schedule. Review the product against the current USITC schedule. No duty estimate has been produced for this code.

Keep the original input, diagnostic payload and source-edition links available for review. Do not retry a deterministic classification failure indefinitely. A rate-limit or service error, by contrast, belongs in a separate retry policy.

What not to do

# Avoid silently substituting a broader code:
# fallback = input_code.replace('.', '')[:8]
# return lookup(fallback)

# Avoid inventing zero duty when a lookup fails:
# duty = payload.get('rate', 0)

An error is not a duty rate, and a parent code is not a reviewed classification.

Verify with primary sources

Current USITC Harmonized Tariff Schedule: review the full hierarchy, legal notes and applicable statistical reporting lines.
CBP CROSS: research relevant classification rulings, including their scope and current status.
CBP trade guidance: consult filing and compliance guidance for the actual entry.

For the endpoint contract and account limits, see the USTariffRates developer documentation. For a complete search-to-lookup example, see our updated API walkthrough.

DEV Community: USTariffRates

Handling Historical HTS Codes Without Inventing a Duty Rate

Reproduce the lookup

Branch on the diagnostic, not only the HTTP code

What not to do

Verify with primary sources