Errors

The v2 error envelope and a complete correction recipe for every well-known code.

Errors are instructions. Every non-2xx response from a /v2/* route is exactly one shape — the error envelope. code is machine-dispatchable, hint says what to DO next, and suggestions carries nearest-ref candidates so a typo'd ref self-corrects in one turn.

Example

5 keys

"response": {

"code": "unknown_entity_refs",

"message": "Unknown entity refs: make:teslla",

"hint": "Resolve free text to refs at GET /v2/entities/resolve?q=teslla",

"refs": [

0: "make:teslla"

"suggestions": [

0: {3 items}

]

}

Unknown refs are named, never guessed

An unknown-but-well-formed ref is ALWAYS a 400 that names the offending ref. Suggestions are advisory — never silently applied. You will never get a quietly fuzzy-matched result or a silent empty set for a bad ref.

The envelope

Field	Type	Required	Description
`code`	string	yes	Machine-dispatchable error code. Well-known codes: invalid_request, invalid_filters, invalid_ref, invalid_vin, invalid_nano_refs, unknown_entity_refs, unknown_entity_domain, unknown_spec_attributes, not_found, unauthorized, forbidden, rate_limited, insufficient_credits, internal_error, unavailable. The set is open — new codes are additive.
`message`	string	yes	Human/agent-readable description naming the offending input
`hint`	string	no	What to do next, e.g. "Resolve free text at GET /v2/entities/resolve"
`docs_url`	string	no	Fetchable Markdown correction page for this error code
`details`	object[]	no	Field-level validation failures (grammar errors)
`details[].path`	string	no	The failing field, e.g. "filters.makes.0"
`details[].message`	string	yes
`refs`	string[]	no	The offending refs/keys, verbatim (unknown_entity_refs, unknown_spec_attributes, invalid_nano_refs)
`suggestions`	object[]	no	Nearest-ref candidates per offending input. Advisory — never silently applied.
`suggestions[].invalid`	string	yes	The offending input, verbatim
`suggestions[].nearest`	object[]	yes	Best candidates, most likely first. Advisory — never auto-applied.
`suggestions[].nearest[].ref`	string	yes	A valid registry ref, e.g. "make:tesla"
`suggestions[].nearest[].name`	string	no	Registry display name, e.g. "Tesla"
`suggestions[].resolve`	string	no	Server-relative resolve URL, e.g. "/v2/entities/resolve?domain=make&q=teslla"

The code set is open: new codes are additive, never breaking. Dispatch on the codes you know and fall back on message/hint.

Error codes

Code	Meaning
`invalid_request`	The request body or parameters did not match the operation's schema.
`invalid_filters`	One or more filters used invalid ref syntax, scalar values, or ranges.
`invalid_ref`	A path or query parameter did not match the `{domain}:{key}` ref grammar.
`invalid_vin`	The supplied VIN failed the platform's length or character rules.
`invalid_nano_refs`	A nano filter did not match the VIN-derived nano key grammar.
`unknown_entity_refs`	The refs were well formed, but the entity registry did not recognize them.
`unknown_entity_domain`	The domain was well formed, but the entity registry does not serve it.
`unknown_spec_attributes`	A `spec.*` filter named an attribute that is not in the current catalog.
`not_found`	The requested route or resource does not exist.
`unauthorized`	The request did not carry a valid API key, session, or internal credential.
`forbidden`	The credential is valid but does not grant access to the requested route group.
`rate_limited`	The credential exhausted the request limit described by the response.
`insufficient_credits`	A hard-stop plan has no allowance or prepaid pack balance left.
`internal_error`	The server failed while processing a request that the caller cannot repair.
`unavailable`	A required platform dependency was temporarily unavailable.

Open a code for what happened, the exact next action, and a working corrected request. Error envelopes link directly to the page's markdown twin so an agent can fetch the recovery recipe without parsing HTML.

HTTP statuses

Status	When
400	Invalid request — grammar failure or unknown-but-well-formed refs, NAMED in `refs`/`details`, with nearest-ref `suggestions` where computable. Never a fuzzy fallback.
401	No valid credential (API key, session, or internal token)
402	Insufficient credits (free-tier hard stop; paid tiers bill overage instead)
404	Resource not found
429	Per-minute rate limit exceeded
500	Internal error