API Changelog

Release 0.3.25: Clearer errors for auto-classification and HS Code Search

These changes affect only requests that previously failed, hung, or returned an unreliable result. Requests that send an hsCode with autoClassify set to "false" (or omitted) are unchanged.

Landed Cost Calculator (POST /calculator)

autoClassify: "true" now requires hsCode. An item with autoClassify: "true" and no hsCode used to return HTTP 500. It now returns HTTP 422 with error 1057, like any other item missing an hsCode:

{
  "code": "400",
  "message": "Landed Cost API Request Has Errors",
  "fieldErrors": [
    { "element": "items[0].hsCode", "code": "1057", "message": "HS Code is required as part of the Item collection" }
  ]
}

An item with autoClassify: "true" and an hsCode is priced on the supplied code, as before.

Auto-classification (autoClassify: "AUTO-CLASSIFY") no longer returns a zero-duty quote when it can’t classify a product. Previously, if no HS code could be found, the request either failed with HTTP 500 or returned a quote priced at zero base duty. A failed classification now fails the whole request with one of these responses:

If you send an Idempotency-Key header, a request that failed this way can’t be replayed: retrying with the same key returns 409 idempotency_attempt_failed. Retry with a new key.

Example:

{
  "schemaVersion": 1,
  "reason": "classification_unavailable",
  "message": "Automatic HS classification is temporarily unavailable. Retry after the Retry-After interval (with a new Idempotency-Key if you send one), or send hsCode for each item."
}

SKU-to-HS-code mapping errors. For accounts that price items from saved SKU mappings, a missing mapping used to fail with HTTP 500. The request is now refused with HTTP 422 and one of two new error codes on items[i].sku:

• 1074: no mapping for the SKU and destination; add the mapping.
• 1075: the mapped HS code isn’t in the destination’s tariff schedule; correct the mapping.

This check applies only when the quote is priced against the tariff. A zero-price item, or a quote below the destination’s duty de minimis, isn’t looked up and isn’t refused.

HS Code Search (POST /hscodesearch and POST /data/hsdocument)

When the classification provider fails (times out, returns an error, or sends an unreadable response), HS Code Search now returns HTTP 503 with reason: "search_provider_unavailable" and a Retry-After header, instead of hanging or returning a “no match” result.

• A request that fails this way does not count toward your trial search allowance.
• A genuine “no match” (the provider answered, but found no HS code) is unchanged and still returns a normal response.

Timeouts

Requests to the classification provider now time out instead of waiting indefinitely. Each call to the classification provider is limited to 20 seconds. A request can make several calls (up to two per auto-classified item, and items are handled one after another), so a whole request can take longer than that.