Skip to main content
help on every error is {DOCS_PUBLIC_URL}/api/errors#{reason} with reason lowercased. Follow hint. Hints name a concrete next call. CLI --json failures and MCP tool failures also expose reason, message, and hint. MCP tool failures use isError: true with a JSON object in content[].text; protocol errors place these fields in JSON-RPC error.data.

AUTH_MISSING

Send Authorization: Bearer <token> on this request. For personal tokens, have the user create one in Settings → Access tokens and provide it through ELA_API_TOKEN.

AUTH_INVALID

For an invalid, expired, or revoked personal token, have the user create a replacement in Settings → Access tokens, then retry with Authorization: Bearer <token>. Personal tokens are not refreshed through OAuth. For an invalid signed-in session, sign in again through the application.

VAULT_FORBIDDEN

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

PERMISSION_MISSING

Use a credential with the missing permission named in the WWW-Authenticate scope parameter. Repeating the request or supplying agent_id will not grant permission. Authenticated note mutations require notes.write; queue and receipt reads also require notes.review. Agents with write-only tokens should hand a queued write’s ID to a reviewer rather than request extra review permission. See Access tokens.

CREDENTIAL_FORBIDDEN

Use a suitable signed-in session for replica mutation, folder rename/delete, session management, activity, export, library deletion, or billing. Adding permissions to a personal token cannot enable those operations. Personal tokens also cannot manage tokens, sessions, checkout, or the billing portal. Agent note writes use POST /v1/notes with notes.write.

PLAN_REQUIRED

This feature is included with Ela Pro. message is one of:
  • Cloud MCP needs Ela Pro.
  • Connecting with a token needs Ela Pro.
  • Creating an access token needs Ela Pro.
  • Ask Ela needs Ela Pro.

ALREADY_SUBSCRIBED

POST /v1/billing/portal to manage the existing Pro subscription.

BILLING_ACCOUNT_NOT_FOUND

POST /v1/billing/checkout to subscribe first. The portal opens only for an account with a Stripe customer.

BILLING_UNAVAILABLE

Retry in a minute. If it keeps failing, the server’s Stripe configuration needs attention (docs/setup/stripe.md).

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.

ACCESS_TOKEN_NOT_FOUND

Use a signed-in session for GET /v1/access-tokens to list ids, then retry DELETE /v1/access-tokens/{id} with an id from that list.

SESSION_NOT_FOUND

Use a signed-in session for GET /v1/sessions to list ids, then retry DELETE /v1/sessions/{id} with an id from that list.

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.

SNAPSHOT_UNAVAILABLE

GET /v1/sync/ops?after_seq=0 to read the full log. The library has ops but no saved snapshot yet.

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.

UNKNOWN_TOOL

Call tools/list, then call an advertised tool. Local MCP is read-only; write_note and edit_note are available only on eligible cloud MCP connections.