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.