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.
Signing in and sessions
Section titled “Signing in and sessions”| 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 |
Account deletion
Section titled “Account deletion”| 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 |
Account recovery
Section titled “Account recovery”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 |
Vaults and sync
Section titled “Vaults and sync”| 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 |
References and entries
Section titled “References and entries”| 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 |
Share links
Section titled “Share links”| 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 |
HTTP and transport
Section titled “HTTP and transport”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.
Crypto
Section titled “Crypto”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.createVaultorimportVaultin an organization: an owner or admin has keys that don’t verify, and nothing was created.err.details.principal(user:<id>) anderr.details.emailname them.