Skip to content

Error codes

Every failure carries a stable code. Programs branch on the code. The message is written for people and may be reworded between versions.

Shapes

The API's own routes answer with one envelope:

{ "code": "vault_section_not_writable", "message": "This key or tool cannot write to that section.", "status": 403 }

A write to a collection that fails field validation names the fields under data, each with its own code:

{ "status": 400, "message": "Failed to create record.", "data": { "key": { "code": "validation_required", "message": "Cannot be blank." } } }

The OpenID Connect endpoints answer { "error": …, "error_description": … }, as OAuth 2.0 specifies.

In the JavaScript SDK

Each shape is decoded into one RevokedError. Its code is the envelope's code, the OAuth error, or the first field's code, in that order. An answer without any of them has the code http_<status>, and a request that got no answer has network or timeout. fields holds the per-field codes.

Status Class
400, 422 ValidationError
401 AuthenticationError
403 PermissionError
404 NotFoundError
409 ConflictError
410 GoneError
413 PayloadTooLargeError
429 RateLimitedError, with retryAfter in seconds
5xx ServerError
no answer NetworkError, TimeoutError
import { RevokedError } from '@kiunke.dev/revoked';

try {
  await revoked.vault.create({ key: 'note', value: 'text', section });
} catch (error) {
  if (error instanceof RevokedError && error.code === 'vault_section_not_writable') {
    // the key may not write to that section
  }
  throw error;
}

Codes

The status is set where an error is raised, so the same code can answer with more than one status. A newer server can send a code missing from this list.

Code Message
access_denied This action is not permitted on this record.
active_workspace_mismatch The selected workspace does not match the active workspace.
alias_cycle An alias cannot point at another alias.
alias_parent_missing The alias parent record does not exist in this workspace.
already_workspace_member This account already has access to this workspace.
api_key_expired This API key has expired.
api_key_not_permitted This action requires a user session; API keys are not accepted.
api_key_vault_scope API keys reach the vault only through assigned sections. At least one section is required.
application_needs_watermark An application link must stamp its files.
archive_empty This share has no files that can be downloaded together.
attestation_check_closed This check was already answered or has expired.
attestation_check_invalid A check names a type without spaces, attesters as domains, and claims as names of letters, digits and underscores.
attestation_check_not_found This check does not exist. The link may be incomplete.
attestation_claim_reserved A claim uses a name the credential format sets itself.
attestation_claims_invalid Claims are a flat set of named values: names of letters, digits and underscores, values of text, numbers or true/false.
attestation_expiry_invalid The end date of an attestation or offer must be in the future.
attestation_identity_mismatch This offer was made for a different identity.
attestation_immutable An attestation's statement cannot be changed once issued. It can be revoked and reissued.
attestation_issue_failed The credential could not be issued.
attestation_key_unsupported The identity's key is of a kind a credential cannot be bound to.
attestation_not_found Attestation not found.
attestation_offer_claimed This offer was already accepted. Offers can be accepted once.
attestation_offer_expired This offer has expired.
attestation_offer_not_found This offer does not exist.
attestation_offer_revoked This offer was withdrawn by its issuer.
attestation_share_closed This link was ended by the person who shared it, or has expired.
attestation_share_invalid A share link names one of your attestations and how many days it stays open, from 1 to 90.
attestation_share_not_found This link does not exist. It may be incomplete.
attestation_subject_invalid An offer names its identity by a fingerprint of 64 hexadecimal characters.
attestation_type_invalid An attestation requires a type of up to 255 characters, without spaces.
attestations_disabled This server does not issue attestations. Issuing is enabled by its operator.
audience_by_owner_only Only the owner can change who sees this, from the app.
audience_invalid The audience must be private, workspace or groups of this workspace.
bookmark_group_not_owned A selected group does not belong to this account.
callback_url_required A callback URL is required.
challenge_identity_required The identityId query parameter is required.
challenge_invalid The handshake challenge is unknown, expired, or already used.
challenge_required A signed handshake challenge is required.
challenge_scope_invalid Unknown challenge scope.
connection_challenge_invalid The PKCE challenge is missing or malformed.
connection_client_invalid A tool must be identified by an https origin (or http on localhost).
connection_draft_invalid The draft values are invalid.
connection_draft_limit_reached Too many open drafts. More are accepted once the owner has answered.
connection_draft_not_found Draft not found or expired.
connection_expired This connection has expired. The tool must be reconnected from the app.
connection_foreign Only a connected tool of the same account can be selected, and it cannot be changed later.
connection_grant_invalid This code is unknown, expired, already used, or does not match its verifier.
connection_not_connected This tool has no active connection to reuse. Connections are made from the app.
connection_not_found Connection not found.
connection_not_permitted The owner has not allowed this tool to do that.
connection_paused This tool is paused by the owner and works again once reactivated.
connection_permission_invalid This permission cannot be granted to a connected tool.
connection_polled This action requires the answer to be sent to the tool's own address. Tools that poll for it cannot perform it.
connection_redirect_invalid The return address must be on the tool's own origin.
connection_revoke_not_allowed The owner has not allowed this tool to revoke links.
connection_unauthorized This connection token is unknown or was disconnected.
connection_vault_not_allowed The owner has not allowed this tool to read the vault.
connection_vault_polled Vault access requires the answer to be sent to the tool's own address. Tools that poll for it cannot read the vault.
connection_vault_reconnect Vault read access requires reconnecting from the tool.
contact_block_target_missing A block requires an account, an email address or a domain.
contact_not_found Contact not found.
contact_nothing_to_send At least one entry must be selected.
contact_route_missing A contact requires an account, a server or an email address.
credential_invalid The credential the issuer returned did not verify, so it was not kept.
credential_not_found This credential does not exist.
dav_link_protected This link is protected and not available over CardDAV.
dav_read_only This address book is read-only.
default_audience_invalid Defaults name sections, links, requests, templates, contacts or attestations, each private or workspace.
duplicate_values Duplicate values are not allowed.
duplicate_workspace_member This user is already a member of this workspace.
email_code_invalid This code is wrong, expired, or was tried too often.
email_code_too_soon A code was just sent to this address. Another can be requested after a minute.
email_send_failed The confirmation email could not be sent.
email_verification_off This server does not confirm email addresses. Accounts are created directly.
email_verification_required The email address must be confirmed with the code sent to it before the account is created.
failed_to_create_record Failed to create record.
failed_to_create_workspace_member The user could not be added to the workspace.
file_alias_unsupported A reference record cannot be a file.
file_download_invalid The download token is invalid or expired. Reopening the link issues a new one.
file_name_invalid A file name cannot be empty or contain path separators.
file_not_allowed Only file records may carry an uploaded file.
file_not_watermarkable This share stamps its files. This file cannot be stamped and is not served.
file_required A file record requires an uploaded file.
file_storage_exceeded This workspace has reached its file storage limit.
file_too_large The file exceeds this server's maximum file size.
forbidden_workspace_access This user does not have access to this workspace.
grant_batch_invalid The batch is empty or exceeds the per-request limit.
grant_events_unverified The events are not signed by the server they claim to come from.
group_name_invalid A group's name is 1 to 80 characters.
group_not_found Group not found.
handshake_failed The handshake could not be completed.
handshake_invalid The provided handshake token is invalid.
handshake_required A handshake token is required for subsequent communications.
identity_fingerprint_invalid An identity fingerprint must be 64 lowercase hexadecimal characters.
identity_not_found Identity not found.
identity_not_owned The selected identity does not belong to this workspace.
identity_required An identity is required for this action.
identity_revoked This identity has been revoked by the server that issued it.
identity_wrong_root This request only accepts identities issued by this server.
invalid_active_workspace The selected active workspace is invalid.
invalid_api_key The supplied X-API-Key is not valid.
invalid_certificate The supplied certificate is invalid.
invalid_request_body The request body could not be read.
invalid_scope One or more requested API key scopes are unknown.
invite_exhausted This invite has already been used.
invite_expired This invite has expired.
invite_inviter_lost_access The creator of this invite can no longer invite members to this workspace.
invite_not_found This invite does not exist.
invite_revoked This invite has been revoked.
invite_wrong_account This invite was issued for a different email address.
last_admin_protected This workspace would be left with nobody who can manage members.
link_connection_foreign A link can only name a connection of the same account, and keeps the one it was created with.
link_content_not_owned A share can hold only records and sections its creator owns or sees.
link_expired This link has expired.
link_hand_over_not_allowed The owner has not allowed this tool to receive links.
link_key_not_found This link has no shared value with that key.
link_max_views_reached This link has reached its maximum number of views.
link_not_found Link not found.
link_password_invalid The supplied password is invalid.
link_password_required A password is required to access this link.
link_paused This link is paused and temporarily unavailable.
link_revoked This link has been revoked.
missing_active_workspace No active workspace is selected for this account.
missing_permission Workspace access does not include this action.
not_authenticated Authentication is required.
not_authorized This request is not permitted.
not_record_editor This item can be changed only by its owner and the members it is opened to for editing.
not_record_owner This record belongs to another user.
not_workspace_admin This action requires the admin role in this workspace.
not_workspace_member This account is not a member of this workspace.
oidc_link_record_invalid A selected entry does not belong to this account.
oidc_name_invalid This name cannot be used. A name is a plain text entry of this account.
oidc_name_too_long This name is too long. A name can be at most 200 characters.
oidc_request_invalid This sign-in has expired or was already used. It must be restarted from the service.
oidc_sign_in_paused This service is paused. Signing in requires reactivating it.
passkey_ceremony_invalid This attempt timed out or was already completed.
passkey_email_invalid The email address is invalid.
passkey_email_taken An account with this email address already exists.
passkey_grant_invalid This code is unknown, expired, already used, or does not match its verifier.
passkey_last The only passkey on an account cannot be removed. Another passkey must be added first.
passkey_not_found Passkey not found.
passkey_origin_invalid Passkeys only work at this server's own address. On a development machine that is localhost, not 127.0.0.1.
passkey_request_invalid The sign-in request is malformed.
passkey_signup_only Accounts are created with a passkey, on this server's sign-in page.
passkey_ticket_invalid This link is unknown, already used, or expired.
passkey_unknown This passkey belongs to no account on this server. It may have been removed, or its account deleted.
passkey_verification_failed The passkey could not be verified.
peer_key_unavailable The sending server's key could not be checked.
permission_escalation Access beyond the granter's own cannot be granted.
presentation_invalid This is not a credential presentation that can be read.
rate_limited Too many attempts. Retry after a short delay.
record_not_found Record not found.
reissue_credential_expired This credential has expired. An expired credential is not moved to a new identity.
reissue_credential_invalid This credential was not issued by this server, or cannot be read.
reissue_credential_revoked This credential was revoked, or already moved to another identity.
reissue_holder_revoked The identity this credential was issued to has been revoked. Its key no longer vouches for another.
reissue_holder_unconfirmed The server of the identity this credential was issued to could not confirm that it still stands.
reissue_identity_mismatch A credential moves only to another identity from the server that issued the current one.
reissue_voucher_invalid The key the credential is bound to did not vouch for the new identity.
reminder_due_required A reminder date is required.
reminder_kind_invalid A reminder is either for a date or for a change.
reminder_record_missing The reminder's entry does not exist or is not in an accessible workspace.
reminder_watch_missing The watched entry does not exist, or is not in the same workspace.
remote_grant_unresolvable The answer could not be read from the server it lives on.
remote_identity_invalid The identity could not be verified with the server that issued it.
remote_origin_invalid The request names a server address that cannot be used.
remote_server_mismatch The server at this address claims to be a different domain.
remote_unreachable The other server could not be reached.
request_account_required An account on this server is required to respond to a request.
request_completed This request has already been completed.
request_expired This request has expired.
request_extra_fields_forbidden Additional fields beyond the template are not allowed for this request.
request_identifier_missing The identifier is missing or does not match.
request_key_invalid One or more submitted keys do not match the required pattern.
request_not_editable This request can only be changed by its owner.
request_not_found Request not found.
request_password_invalid The supplied password is invalid.
request_password_required A password is required to access this request.
request_paused This request is paused and temporarily unavailable.
request_required_missing Required template fields are missing from the submission.
request_revoked This request has been revoked.
sealed_epoch_stale This workspace's encryption key has changed. Reload and retry.
sealed_fields_restricted This entry is end-to-end encrypted. Changing it requires a newer app version.
sealed_file_watermark A share that stamps its files cannot carry an encrypted file: the server cannot read it to stamp it.
sealed_identity_keys_pending Some identity keys in this workspace are still under its encryption key. They move by themselves once their owners open the app.
sealed_invalid This encrypted data is not in the expected form.
sealed_key_missing The encryption key for this workspace is not available.
sealed_link_content A link can carry an encrypted entry only with a key for it, made by a device that can open the entry.
sealed_link_seals_missing This entry is on links that need its new key along with the change.
sealed_links_affected This entry is shared by links, which would stop showing it once encrypted.
sealed_record_unsupported End-to-end encrypted entries are not supported here yet.
sealed_version_conflict This was changed on another device first. Reload and retry.
section_share_by_person_only Only the section's owner can share it with members, from the app.
section_view_invalid The view must be a version 1 layout with an id, the keys it matches and at least one block.
sign_in_not_found Sign-in not found.
signature_invalid The supplied challenge signature is invalid.
signups_disabled This server does not accept new registrations.
template_not_owned The selected template does not belong to this workspace.
template_schema_invalid A template schema is an object with "records" and "sections", each a list of entries with a key.
two_factor_already_enabled Two-factor authentication is already turned on for this account.
two_factor_challenge_invalid This sign-in has expired or was already completed. Signing in starts again with the passkey.
two_factor_code_invalid This code is not the one the authenticator app shows right now.
two_factor_enforced This server requires two-factor authentication, so it cannot be turned off.
two_factor_not_enabled Two-factor authentication is not turned on for this account.
two_factor_not_pending No authenticator app is being set up. Setting up starts again with a new secret.
two_factor_required This account asks for a code from its authenticator app before signing in.
two_factor_setup_required This server requires two-factor authentication. Set up an authenticator app first.
unknown_feature One or more requested features are unknown.
user_not_found User not found.
validation_insufficient_permissions Modifying this field is not permitted.
validation_required A required value is missing.
vault_key_taken A record with this key already exists.
vault_not_allowed This key or tool was not given any part of the vault.
vault_read_only Only records written with this key or tool can be changed with it.
vault_section_invalid A selected section is not in this workspace.
vault_section_not_writable This key or tool cannot write to that section.
vault_storage_exceeded This key or tool has reached its vault storage limit.
watermark_text_invalid A stamp text must be a single line of 1 to 120 characters.
webhook_delivery_not_found Delivery not found.
webhook_disabled This webhook is disabled.
webhook_events_invalid At least one event from the event list is required.
webhook_limit_reached This workspace has reached its webhook limit.
webhook_not_found Webhook not found.
webhook_url_invalid A full http:// or https:// address reachable by this server is required.
workspace_limit_reached The maximum number of workspaces has been reached.
workspace_member_limit_reached This workspace has reached the maximum number of members.
workspace_not_found Workspace not found.