Docs / Errors

Errors

Every error has the same body. code is stable and safe to branch on; message says what to do instead; details depends on the code.

{
  "error": {
    "code": "jurisdiction_not_found",
    "message": "no jurisdiction 'us-washington'; find slugs with GET /v1/jurisdictions?q=<name>",
    "docs_url": "https://juriset.dev/docs/errors#jurisdiction_not_found",
    "details": {
      "suggestions": [
        "us-wa"
      ]
    }
  }
}

The same fields are repeated at the top level, with status and status_page, for clients written against the first version of the API. Errors are sent with Cache-Control: no-store. Which endpoint returns which code is in the API reference.

Code	Status	Meaning and what to do
`http_error`	400	Another HTTP-level error; `status` and `message` say which.
`invalid_api_key`	401	The header is not `Bearer <key>`, the key is not a Juriset key or is another environment's, or no such key exists. Check it was copied whole.
`missing_api_key`	401	This needs an API key: send `Authorization: Bearer jrs_live_…`. A free key comes from https://juriset.dev/account. Reads of today's rules need no key (the keyless tier).
`revoked_api_key`	401	The key was revoked (`details.revoked_at`). Use another key from your account.
`plan_required`	403	The caller's plan does not include this feature (`details.feature`); `details.plans` lists the plans that do. Today's rule and `upcoming` are in every plan, keyless included.
`read_only_key`	403	A read-only key (the site's own) tried to write.
`domain_not_found`	404	Unknown domain; `details.domains` lists the known ones.
`jurisdiction_not_covered`	404	Juriset does not cover this rule type in this jurisdiction (for example a city). `details.nearest_covered` names the nearest level that is covered; its rule may not be the whole answer here.
`jurisdiction_not_found`	404	Unknown jurisdiction slug; `details.suggestions` lists likely ones. Find slugs with `GET /v1/jurisdictions?q=`.
`not_covered_for_date`	404	`as_of` is before the date Juriset's data for this rule is authoritative from (`details.covered_since`).
`not_found`	404	No such endpoint. The routes are listed at `/openapi.json` and https://juriset.dev/docs.
`rule_type_not_found`	404	Unknown rule type; `details.rule_types` lists the known ones (`GET /v1/rule-types`).
`snapshot_not_found`	404	No stored snapshot with that id is cited by a published version; use a `snapshot_url` from a rule response.
`version_not_found`	404	No published version has this id or number. Version ids look like `rv_01JC3…` (26 characters after `rv_`) and come from a rule response's `id`; numbers are in the rule's history.
`method_not_allowed`	405	The endpoint exists but not with this HTTP method.
`nothing_published`	409	Nothing is published for this rule yet, so there is no value to report on.
`invalid_parameter`	422	A parameter or body field is malformed; `details.problems` lists each one.
`quota_exceeded`	429	This month's lookups are used: the plan's included lookups. `details.resets_at` says when the count starts again; upgrade for more.
`rate_limited`	429	More requests than the plan allows: per second for a key, per hour or per day for keyless callers. Wait `Retry-After` seconds; the `RateLimit-*` headers show what is left. A free key lifts the keyless limits.
`too_many_reports`	429	More than 20 issue reports from this key today (UTC).
`internal_error`	500	Something failed on our side; it has been reported. Retry later, and see the status page if it persists.
`overloaded`	503	Juriset is answering more requests than it can at this moment. Retry after `Retry-After` seconds; the request was not billed.
`snapshots_unavailable`	503	Snapshot storage cannot be reached here. Retry later; the citation's `url` is the live source.