Error envelope
Every non-2xx response returns the same JSON envelope. Theerror
field is a human-readable summary; code is a stable machine token;
request_id matches the X-Request-Id response header.
issues array of { path, message }
objects sourced from Zod, one entry per invalid field.
HTTP status codes
Common error codes
MISSING_API_KEY
Status: 401. The Authorization header is missing or does not start
with Bearer . Add the header.
INVALID_API_KEY_FORMAT
Status: 401. The bearer token does not match the sk_live_... or
sk_test_... format. Copy the raw key from Settings > API keys
without trimming.
INVALID_API_KEY
Status: 401. The prefix matched a row but the full key hash did
not verify. Usually a typo. Rotate if you suspect the key was
truncated in a secret manager.
API_KEY_REVOKED
Status: 401. The key was revoked. Mint a new one.
TIER_DOWNGRADED
Status: 402. The organization dropped below the Growth tier. The
key is still valid; upgrade to resume.
QUOTA_EXCEEDED
Status: 402. Monthly quota exhausted for the current billing period.
Wait for the reset on the first of the next month or upgrade tier.
RATE_LIMIT_EXCEEDED
Status: 429. See Rate limits for the retry pattern.
MISSING_HS_CODE
Status: 422. A line in /v1/calc has no hs_code and inline
classification failed to produce one above the confidence threshold.
Call /v1/classify first, or pass a longer, more descriptive
description.
UNSUPPORTED_DESTINATION
Status: 422. The destination_country is outside the covered list.
Coverage is documented in the rates endpoint reference.
DOMESTIC_SHIPMENT
Status: 422. origin_country equals destination_country. There is
no landed cost to calculate.
INTERNAL
Status: 500. Something failed inside the engine. The request_id in
the envelope is enough for support to pull the call log. Send it to
info@growyourbrand.io.
Bulk endpoints and partial failures
/v1/calc/bulk and /v1/compare do not fail the whole batch on
row-level errors. The response body carries an errors (or
per-origin) array alongside results. A 200 status only means the
request itself was accepted; always inspect the payload for per-row
outcomes.