Skip to main content
help on every error is {DOCS_PUBLIC_URL}/api/errors#{reason} with reason lowercased. Follow hint. Vocabulary is the initial set from the agentic API plan.

​
AUTH_MISSING

Send Authorization: Bearer <token> on this request.

​
AUTH_INVALID

Request a new access token from the authorization server, then retry with Authorization: Bearer <token>.

​
VAULT_FORBIDDEN

Retry with a token whose vault_id or mapped org_id matches a vault.

​
PERMISSION_MISSING

Retry with a token that includes the missing permission named in the WWW-Authenticate scope parameter.

​
NOTE_NOT_FOUND

GET /v1/notes to list slugs in this vault, then retry with a slug that exists.

​
VERSION_NOT_FOUND

GET /v1/notes/{note}:listRevisions to list revision ids, then retry restore / rollback with an id from that list.

​
FOLDER_NOT_FOUND

GET /v1/folders to list paths, then retry with an existing folder path.

​
ATTACHMENT_NOT_FOUND

GET /v1/attachments to list file names, then retry with a name that exists.

​
ATTACHMENT_AMBIGUOUS

Retry GET /v1/attachments/{file_name}?sha256= with one sha256 from details metadata.

​
PENDING_WRITE_NOT_FOUND

GET /v1/writes or GET /v1/writes/{id} to list pending write ids, then retry with an id that exists.

​
ROUTE_NOT_FOUND

GET /openapi.json to discover registered paths, then call a documented route.

​
VALIDATION_FAILED

Fix the fieldViolations listed in details, then retry the same request.

​
INVALID_FILTER

GET /openapi.json and retry with a filter that uses only documented fields and operators. See filters.

​
INVALID_UPDATE_MASK

Retry PATCH with update_mask listing only title, content, folder, tags, status, or frontmatter.<key>.

​
UNSAFE_PATH

Retry with a vault-relative path that stays inside the vault and does not escape.

​
IDEMPOTENCY_KEY_MISSING

Retry the write with an Idempotency-Key header unique to this operation.

​
IDEMPOTENCY_KEY_REUSED

Retry with a fresh Idempotency-Key for this different request body.

​
VERSION_MOVED

GET /v1/notes/{note} to read the current version_id, then retry :edit with that version_id and a fresh Idempotency-Key.

​
NAME_COLLISION

GET /v1/folders or GET /v1/notes and retry with a path that does not already exist.

​
ALREADY_DECIDED

GET /v1/writes?status=applied or GET /v1/writes?status=rejected to list the decision; do not retry the same approve or reject.

​
ALREADY_ENABLED

GET /v1/sync/e2ee; private notes are already enabled for this vault.

​
EDIT_AMBIGUOUS

Retry :edit with a longer unique old_string that matches exactly one place.

​
EDIT_MATCH_NOT_FOUND

GET /v1/notes/{note} and retry :edit with an old_string that appears in the current body.

​
WRITE_REFUSED

GET /v1/vault/write-settings and GET /v1/writes, then retry with a payload the policy allows.

​
WRITE_BUDGET_EXCEEDED

GET /v1/writes for a reviewer to apply remaining work, or wait until the budget window resets and retry with a fresh Idempotency-Key.

​
RATE_LIMITED

Wait the Retry-After seconds, then retry the same request with the same Idempotency-Key.

​
SYNC_COMPACTED

GET /v1/sync/snapshot, then GET /v1/sync/ops with after_seq set to compacted_through_seq from details.

​
STORAGE_UNAVAILABLE

Set DATABASE_URL and start Postgres, then retry this request.

​
BLOB_STORE_UNAVAILABLE

Set BLOB_*, then retry GET /v1/attachments/{file_name}.

​
UNSUPPORTED_MEDIA_TYPE

Retry POST /v1/attachments with an allowed attachment type.

​
PAYLOAD_TOO_LARGE

Retry POST /v1/attachments with a file under the documented byte cap.

​
INTERNAL

Retry the same request; if it persists, include the requestId when reporting the failure.