Errors

Every error shares one shape. The code is stable and is what you should branch on; the message is for humans and may be reworded.

404 Not Found

{
  "error": {
    "code": "resource_not_found",
    "message": "No nomenclature code was found for 999999."
  }
}

Additional fields

Some errors carry extra fields. They are present only where they apply, so check for them rather than assuming.

Field	When present	Meaning
`upgrade_to`	403, 429 quota	The cheapest plan that would have served this request.
`parameter`	400	Which query parameter was at fault.
`documentation_url`	401, 403, 429	The page that explains this class of error.

403 Forbidden

{
  "error": {
    "code": "endpoint_not_available_on_plan",
    "message": "Historical tariffs (?at=) is not available on your plan. Upgrade to Developer to use it.",
    "upgrade_to": "Developer",
    "documentation_url": "https://example.com/docs/plans"
  }
}

Every error code

Code	Status	What to do
`invalid_api_key`	401	Check the key is present, correct and not revoked.
`invalid_parameter`	400	Read `parameter`; the message names the accepted values.
`invalid_date`	400	Dates are ISO-8601, e.g. 2026-03-01.
`resource_not_found`	404	The code or resource does not exist. Not retryable.
`rate_limit_exceeded`	429	Back off and retry; the limit is per minute.
`monthly_quota_exceeded`	429	Wait for the reset on the 1st, or upgrade.
`endpoint_not_available_on_plan`	403	Upgrade to the plan in `upgrade_to`.
`internal_error`	500	Ours, not yours. Retry; if it persists, tell us.

Retrying

429 and 500 are worth retrying with exponential backoff. 400, 401, 403 and 404 are not, the same request will fail the same way, and retrying it only spends quota.

A 404 for a code means that code is not in the published data, which is a real answer rather than a failure. 31,231 codes exist; a six-digit number outside that set has no record.