REST API (v2)

Errors

The shared error shape and canonical code list.

Errors

Every error response — REST or MCP — carries the same { ok: false, errors: [...] } shape. code is stable; message and fix_hint are human-readable.

Shape

{
  "ok": false,
  "errors": [
    {
      "code": "element_not_found",
      "message": "Element 'missing' not found in ai@2026-04-16-beta.",
      "path": "elements[0].element_id",
      "fix_hint": "Use GET /api/v2/schemas/:version/elements to enumerate available element ids."
    }
  ]
}

Field	Required	Meaning
`code`	yes	Stable machine-readable code from the table below.
`message`	yes	Human-readable diagnostic.
`path`	no	JSON path into the caller's payload (e.g. `elements[3].category_id`).
`fix_hint`	no	Short actionable instruction.

Adding new code values is additive; renaming or removing is a breaking change (guarded by snapshot fixtures in the repo).

Codes

Transport-level (HTTP status mirrors the code)

Code	HTTP	Meaning
`bad_request`	400	Malformed input — version path param, query params, request body, or invalid cursor.
`not_found`	404	Unknown version, element, symbol, variant, or shape.
`payload_too_large`	413	Request body exceeds the configured byte limit.
`rate_limited`	429	Client exceeded the rate-limit bucket. `Retry-After` header indicates the wait.
`timeout`	504	Request exceeded the per-route wall-clock budget.
`upstream_error`	502	Schema-store (R2) read failed.
`internal_error`	500	Unexpected server error.

Semantic — surfaced in 200 bodies

Code	Raised by	Meaning
`parse_error`	`POST /validate`, MCP validate / render	Datachain shape failed Zod validation. `path` locates the offending field.
`element_not_found`	MCP `get_elements` (per-id), MCP `get_icon_url`, MCP `get_element`	Element not present in the version.
`element_ids_too_many`	MCP `get_elements`	>100 unique ids after dedupe.
`unknown_version`	MCP tools	Manifest missing for the resolved version.
`unknown_variant`	MCP `get_icon_url`	Variant not in the element's `icon_variants`. `fix_hint` lists valid variants.
`invalid_arguments`	MCP tools	Argument failed the tool's Zod input schema.
Semantic validator codes	`/validate`, `render_datachain`, `validate_datachain`	Shape-valid but semantically wrong — required categories missing, placement invalid, cardinality violated, etc.

Rate limiting

Read endpoints share one bucket; POST /validate uses a dedicated tighter bucket. Setting DTPR-Client: <name> opts your traffic into a per-client bucket. On exceed:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "ok": false,
  "errors": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded.",
      "fix_hint": "Wait 60 seconds or set `DTPR-Client` for a dedicated bucket."
    }
  ]
}

Errors

Errors

Shape

Codes

Transport-level (HTTP status mirrors the code)

Semantic — surfaced in 200 bodies

Rate limiting

See also