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. |