Errors and versions

The error envelope

Every error has the same shape and an HTTP status that matches its code:

JSON

{
  "error": {
    "code": "forbidden",
    "message": "This API token lacks the scope docs:write",
    "hint": "Optional advice on what to do next",
    "details": { "required": ["docs:write"], "granted": ["docs:read"] }
  }
}

message is written for people and may change. Branch on code. hint and details are optional.

Status	Code	Meaning
400	`invalid_input`	The input does not match the schema. `details` may list the problems.
401	`unauthenticated`	No token, or the token was revoked or has expired.
403	`forbidden`	You lack access to the page, the token lacks a scope, or the operation needs a signed-in session.
404	`not_found`	It does not exist, or you cannot see it.
404	`unknown_operation`	No such operation.
409	`conflict`	The data changed since you read it (`expectedVersion`), or the change clashes with the current state.
429	`rate_limited`	Too many attempts. Wait for the `Retry-After` seconds.
500	`internal`	Our fault. Retry later.

Warnings

Some operations succeed partly. A body edit that matched nothing is skipped while the other edits apply. The result then lists warnings, and the response also carries them in the Lydie-Warnings header as a JSON array.

Versions

The API is versioned by date. The current version is 2026-11-12. Pin the version you built against by sending it with each request:

HTTP

Lydie-Version: 2026-11-12

The OpenAPI document always describes the current version.