Getting Started

Errors

Every error response is JSON with an error string and, when applicable, a machine-readable code and remediation-friendly message.

Status

Code

When

Fix

400

invalid body

Zod validation failed. Response body includes an issues array with per-field detail.

Correct the failing field and retry.

400

unsupported_destination

Destination country is not one of the 220+ LandedFees supports.

Check /coverage and switch to a supported destination.

401

unauthorized

Missing, malformed, or revoked API key.

Verify the Authorization header and issue a new key from the dashboard if needed.

402

quota_exceeded

Monthly quota exhausted on the current plan.

Upgrade at /pricing or wait for the monthly reset.

422

MISSING_HS_CODE

One or more line items lack an HS code and inline classification failed.

Supply an explicit hs_code or a more descriptive product name.

422

DOMESTIC_SHIPMENT

origin_country and destination_country are the same.

Landed cost only applies to cross-border movements. Adjust one country.

422

DATA_NOT_AVAILABLE

Verified rate data is not yet loaded for the requested country.

Choose a covered country (see /coverage) or contact support to request expedited coverage.

429

rate_limited

Sliding-window rate limit exceeded.

Honor Retry-After and back off.

500

internal

Unexpected server error. Response includes a detail string.

Retry idempotently; contact support if the error persists.

Handling errors

HTTP/2 400
content-type: application/json

{
  "error": "invalid body",
  "issues": [
    {
      "path": ["origin_country"],
      "message": "String must contain exactly 2 character(s)"
    }
  ]
}