Errors

Every /v1 error is application/problem+json (RFC 9457): what went wrong, in one sentence, and what fixes it. An agent or script can act on it without reading this page.

{
  "type": "https://usetruenote.com/docs/errors#insufficient_scope",
  "title": "This token lacks a scope",
  "status": 403,
  "detail": "This agent's access doesn't include context:write. The person can allow it under Connected agents in Truenote.",
  "error": "insufficient_scope",
  "scope": ["context:write"],
  "fix": "Ask the person to allow context:write for this connection under Connected agents in Truenote (an OAuth client can re-authorize with the scope in WWW-Authenticate), then send the request again.",
  "requestId": "…"
}

Field	Meaning
type	This page, at the error’s code
title, status	The kind of error and the HTTP status
detail	What went wrong, in plain words
error	The stable machine code (below)
field	The request field it’s about, when it’s about one (a 400’s bad parameter, a 409’s conflicting name)
fix	What to do about it
scope	The scopes the token is missing (insufficient_scope only); WWW-Authenticate carries the whole set to re-authorize with
requestId	The request, to quote to support

An MCP tool error carries the same thing: its text is the detail, the field and the fix, and the problem object is the result’s structuredContent.

Codes

error	Status	Fix
invalid_request	400	Correct the field named in field (the body’s schema is in the OpenAPI spec) and send it again.
unauthorized	401	Send a bearer token: a personal access token from Connected agents, or an OAuth access token issued for /v1.
invalid_token	401	The token is expired, revoked or for another resource: refresh it, or get a new one. A revoked token can’t be renewed.
subscription_required	402	The person starts or renews their subscription in Truenote.
insufficient_scope	403	Ask the person to allow the scopes in scope for this connection under Connected agents, then retry.
forbidden_origin	403	Call from a server or a CLI (no Origin header), or from an origin the server allows.
not_found	404	Check the id (ids come from the GET routes). Something the token isn’t allowed to see answers the same 404.
conflict, name, duplicate, archived, storage_full…	409	The detail says what the current state is and what would be accepted (a name in use, a bucket that isn’t empty, the same file twice, documents full).
too_large	413	Send a smaller body (documents are 10 MB at most).
rate_limited	429	Wait the seconds in Retry-After, then retry (240 requests a minute per token).
internal	500	Retry in a moment; if it keeps happening, tell support@usetruenote.com the requestId.
not_configured	503	The operator sets that up; nothing a caller can do.