Skip to content
OpenVireoDeveloper
GitHub

Errors

Every error code and what to do about it.

Every error the SDK throws on purpose is an OpenVireoError with a machine-readable code. Errors from a server also carry the HTTP status, and are HttpErrors with the response body and retryAfter (seconds, from Retry-After). Messages are for people and may change; branch on code.

import { isOpenVireoError, isUnreachable } from "@openvireo/sdk";
try {
await account.login({ email, password });
} catch (e) {
if (isOpenVireoError(e, "invalid_secret_key")) {
await account.login({ email, password, secretKey: await askForSecretKey() });
} else if (isUnreachable(e)) {
// no network, or a gateway answered 502/503/504: try again later
} else {
throw e;
}
}

isUnreachable(e) is true for network_error and for 502, 503 and 504: the server couldn’t be reached, as opposed to refusing the request.

Code Status Meaning What to do
unauthorized 401 Wrong email or password, a Secret Key that doesn’t match, or a session that is no longer valid. On sign-in and unlock, err.details.reason tells which: opaque_refused (wrong email or password) or keyset_unwrap_failed (the password was accepted but the Secret Key doesn’t match; offline, a wrong password) Ask again (for the Secret Key on keyset_unwrap_failed), or sign in again
invalid_secret_key The Secret Key is malformed, or this device has none for the account Ask for the Secret Key (Emergency Kit)
mfa_required The account has two-factor authentication and no code was given Pass totp
invalid_mfa 401 Wrong two-factor code With a totp function, login asks again by itself
mfa_expired 401/410 The sign-in timed out or the code was wrong too often Start the sign-in again
session_expired 410 The session, or a link such as a recovery link, expired or was used Sign in again
token_reused 401 A refresh token was used twice, a sign it was copied; the server ends the session Sign in again; onSignedOut reports it
signed_out The call needs a signed-in account Sign in first
weak_kdf The account’s password hashing settings are below the minimum the client accepts Report it; don’t continue
opaque_failed The OPAQUE module couldn’t load or a protocol step failed Check that the WASM module is bundled
Code Status Meaning What to do
account_pending_deletion 403 The account is scheduled for deletion; err.details.scheduledFor is the erase date Offer restoreAccount, or sign out
deletion_blocked 409 The user is the only owner of organizations with other members; err.details.orgs lists them as [{ id, name }] Make someone else an owner, or delete the org, then try again
confirm_mismatch 400 The typed email isn’t the account’s Ask again
not_a_member 409 transferVault to someone without access to the vault Share it with them first

See Account recovery for recovery_not_ready, recovery_cancelled, restore_locked and invalid_proof.

On the hosted service, plans limit what an account or organization can create. Self-hosted servers have no limits. Nothing is locked when a limit is reached: existing vaults keep opening and syncing.

Code Status Meaning What to do
plan_limit 402 Creating this (a vault, a share, a member, a service account) would go over the plan. err.details has limit (which one, e.g. personal_vaults), max, current, plan and upgradeUrl Offer err.details.upgradeUrl, or remove something first
quota_exceeded 413 The vault is larger than the plan’s storage per vault; err.details.max is the limit in bytes Make the database smaller (attachments, history), or upgrade

A paid plan’s billing (plan.billing in auth.me(), SPEC §19) says who bills it. Follow manage: website means the account site’s pricing page; app_store means the plan was bought in the iOS app and belongs to an Apple ID, so only its owner can change or cancel it (on their iPhone, or at APPLE_SUBSCRIPTIONS_URL). The SDK never sells or cancels In-App Purchase. These codes come from the In-App Purchase routes the iOS app uses:

Code Status Meaning What to do
billed_by_stripe 409 The Apple purchase was recorded, but a plan bought on the website is still in force Tell the user to cancel one of them
apple_subscription_bound 409 This Apple subscription already belongs to another account or organization; it never moves Sign in to that account, or cancel it at Apple
apple_verification_failed 400 The signed transaction didn’t verify Retry; report it if it persists
Code Status Meaning What to do
forbidden 403 The account or service account doesn’t have the role this needs (e.g. write for a change) Ask a vault manager for access
not_found 404 No such vault, entry, member, …
not_available_offline Offline, and this vault was never synced on this device Go online once
vault_key_mismatch The password, password hash or key file doesn’t open the file (a local database, or the server copy) Self-hosted: ask for the database’s new password. Accounts: the keys are out of date; reload the vault list
no_vault_key The account holds no usable key for this vault Reload the vault list; ask a manager to share it again
too_many_conflicts 412 The vault kept changing during the sync, five times in a row. Local changes are kept Sync again
rotation_pending 409 revoke or rotate: another account started a key rotation on this vault and hasn’t finished it (one this account started is finished for it). err.status is 409; the server lets a new rotation replace it after 24 hours Ask the other manager to open the vault, or try again later
server_rolled_back The server returned an older copy than this device already synced: restored from a backup, or tampered with Ask the user; vault.sync({ acceptServerState: true }) merges anyway
server_lost_database The server no longer has a database this device synced before Ask the user before uploading it again
not_sync_server the page’s SelfHostedSync.health(): the address answers, but not as an OpenVireo sync server (a web page, a 404, other JSON) Check the URL (path, port)
vault_upload_failed importVault created the vault, but the first upload failed (VaultUploadError, with .vault) e.vault.sync() later
kdbx_error The file couldn’t be read or written as KDBX, or the vault isn’t open
merge_failed The merge couldn’t combine the two copies Report it, with the databases if possible
Code Meaning
invalid_reference Not a valid ov:// reference (empty segment, bad percent-encoding, missing field)
entry_not_found No entry, or several, match the reference; use the entry UUID when titles repeat
conflict (409) create: "only" and the entry exists; on the server, also an email that is taken or a key version that moved on
Code Status Meaning What to do
not_found 404 The link expired, was opened as often as allowed, was revoked, or never existed Ask the sender for a new link
passcode_required The link needs a passcode and none was given Ask for it
invalid_passcode 403 Wrong passcode; details.attemptsLeft says how many tries are left before the link ends Ask again
invalid_link The link is incomplete (no key after #) Ask the sender to send it again
too_large The content is over 64 KiB Share fewer fields
invalid_totp A one-time code field isn’t a valid otpauth://totp URI Show the value as text

Server errors keep the server’s code; without one, the status decides:

Status Code
400 invalid_request
401 unauthorized
402 plan_limit
403 forbidden
404 not_found
409 conflict
410 gone
412 precondition_failed
428 precondition_required
429 rate_limited (see retryAfter)
5xx server_error

network_error means the request never got an answer, and aborted that your AbortSignal cancelled it.

insecure_url means a URL isn’t https://, so nothing was sent. Plain http:// is only allowed for this computer: localhost, *.localhost, 127.0.0.0/8 and [::1]. The SDK checks the issuer you pass, every URL in the server’s openvireo-configuration, and self-hosted sync servers.

decryption_failed, unsupported_version, invalid_public_keys, invalid_token and low_order_point mean data didn’t decrypt or verify: wrong key, corrupted data, a malformed token, or keys whose signature doesn’t match. They shouldn’t happen in normal use. Don’t retry them; report them.

Two invalid_public_keys cases are expected and need the user:

  • shareWithKeys: the person’s keys changed since their fingerprint was shown (they reset their account). Look them up again and have the user compare the new fingerprint.
  • createVault or importVault in an organization: an owner or admin has keys that don’t verify, and nothing was created. err.details.principal (user:<id>) and err.details.email name them.