# Errors

> What a /v1 error looks like (application/problem+json), every error code, and what fixes each one. MCP tool errors say the same.

Canonical: https://usetruenote.com/docs/errors

Every `/v1` error is `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)): what went wrong, in one sentence, and what fixes it. An agent or script can act on it without reading this page.

```json
{
  "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](https://app.usetruenote.com/v1/openapi.json)) 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. |