Errors

Every Vault error carries a stable numeric error_code and a machine-readable reason. This page lists the logical error codes Vault can return, across its domain groups (2_3xx) and infrastructure groups (2_6xx). For the full error envelope (the google.rpc.Status shape, the reason and metadata fields, and how codes are structured) see Errors.

Vault codes begin with 2 (for example 2301003, read as 2_301_003: service, group, specific error). The wire value is always the flat integer; you can match on either error_code or reason, both are stable.

The Status column is the canonical gRPC status the error maps to, which the gateway renders as the matching HTTP status (see the status codes table).

Two of these families are on the alpha track

The crypto-key codes (2304…, 2305…) and the capsule codes (2319…) belong to capabilities served under /vault/alpha/, whose shape may still change. See engine selection for how a request selects its engine, and the overview for which capabilities sit on which track.

Code	Reason	Status	Description
2300001	VAULT_OPERATION_PROGRESS_OUT_OF_RANGE	INVALID_ARGUMENT	Vault operation progress must be between 0 and 100.
2300002	VAULT_OPERATION_END_TIME_BEFORE_START_TIME	INVALID_ARGUMENT	Vault operation end time must not be before start time.
2300003	VAULT_OPERATION_NOT_FOUND	NOT_FOUND	Vault operation not found.
2300004	VAULT_OPERATION_ERRORS_REQUIRE_ERROR_STATUS	INVALID_ARGUMENT	A vault operation carrying errors must have status ERROR.
2300005	OPERATION_SCOPE_TYPE_NOT_VALID	INVALID_ARGUMENT	Operation scope type is not valid.
2301001	SECRET_NAME_NOT_VALID	INVALID_ARGUMENT	Secret name must match ^[a-z0-9][a-z0-9/\-_]{1,254}[a-z0-9]$ (3 to 256 characters).
2301002	SECRET_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Secret workspace ID is required.
2301003	SECRET_NOT_FOUND	NOT_FOUND	Secret not found.
2301004	SECRET_ALREADY_EXISTS	ALREADY_EXISTS	A secret with this name already exists in the workspace.
2301005	SECRET_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Secret is not marked for deletion.
2301006	SECRET_VERSION_NOT_FOUND	NOT_FOUND	Secret version not found.
2301007	SECRET_VERSION_ALREADY_DESTROYED	FAILED_PRECONDITION	Secret version is already destroyed.
2301008	SECRET_DELETION_FAILED	UNAVAILABLE	Failed to delete secret in the vault backend.
2301009	SECRET_WORKSPACE_NOT_FOUND	NOT_FOUND	The workspace this secret belongs to does not exist.
2302001	SECRET_VERSION_SECRET_ID_NOT_VALID	INVALID_ARGUMENT	Secret version’s parent secret ID is required.
2302002	SECRET_VERSION_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Secret version’s workspace ID is required.
2302003	SECRET_VERSION_NUMBER_NOT_VALID	INVALID_ARGUMENT	Secret version number must be a positive, monotonically increasing integer.
2302004	SECRET_VERSION_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Secret version is not marked for deletion.
2304001	CRYPTO_KEY_NAME_NOT_VALID	INVALID_ARGUMENT	Crypto key name must match ^[a-z0-9][a-z0-9/\-_]{1,254}[a-z0-9]$ (3 to 256 characters).
2304002	CRYPTO_KEY_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Crypto key workspace ID is required.
2304003	CRYPTO_KEY_ALGORITHM_DOES_NOT_MATCH_PURPOSE	INVALID_ARGUMENT	Crypto key algorithm is not compatible with its purpose.
2304004	CRYPTO_KEY_MIN_DECRYPTABLE_VERSION_NOT_VALID	INVALID_ARGUMENT	Crypto key minimum decryptable version must be >= 1.
2304005	CRYPTO_KEY_NOT_FOUND	NOT_FOUND	Crypto key not found.
2304006	CRYPTO_KEY_ALREADY_EXISTS	ALREADY_EXISTS	A crypto key with this name already exists in the workspace.
2304007	CRYPTO_KEY_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Crypto key is not marked for deletion.
2304008	CRYPTO_KEY_ALGORITHM_NOT_VALID	INVALID_ARGUMENT	Crypto key algorithm is required and must be a recognised value.
2304009	CRYPTO_KEY_WORKSPACE_NOT_FOUND	NOT_FOUND	The workspace this crypto key belongs to does not exist.
2304010	CRYPTO_KEY_PURPOSE_NOT_VALID	INVALID_ARGUMENT	Crypto key purpose is required and must be a recognised value.
2304011	CRYPTO_KEY_PROTECTION_LEVEL_NOT_VALID	INVALID_ARGUMENT	Crypto key protection level is required and must be a recognised value.
2305001	CRYPTO_KEY_VERSION_CRYPTO_KEY_ID_NOT_VALID	INVALID_ARGUMENT	Crypto key version’s parent crypto key ID is required.
2305002	CRYPTO_KEY_VERSION_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Crypto key version’s workspace ID is required.
2305003	CRYPTO_KEY_VERSION_NUMBER_NOT_VALID	INVALID_ARGUMENT	Crypto key version number must be a positive, monotonically increasing integer.
2305004	CRYPTO_KEY_VERSION_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Crypto key version is not marked for deletion.
2305006	CRYPTO_KEY_VERSION_NOT_FOUND	NOT_FOUND	Crypto key version not found.
2305007	CRYPTO_KEY_VERSION_ALREADY_DESTROYED	FAILED_PRECONDITION	Crypto key version is already destroyed.
2305008	CRYPTO_KEY_VERSION_NOT_SCHEDULED_FOR_DESTRUCTION	FAILED_PRECONDITION	Crypto key version has no pending destruction to cancel.
2307001	CERTIFICATE_AUTHORITY_NAME_NOT_VALID	INVALID_ARGUMENT	Certificate authority name must match ^[a-z0-9][a-z0-9\-_]{1,254}[a-z0-9]$ (3 to 256 characters).
2307002	CERTIFICATE_AUTHORITY_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Certificate authority workspace ID is required.
2307003	CERTIFICATE_AUTHORITY_INTERMEDIATE_MISSING_PARENT	INVALID_ARGUMENT	Intermediate certificate authority requires a parent CA reference.
2307004	CERTIFICATE_AUTHORITY_VALIDITY_WINDOW_NOT_VALID	INVALID_ARGUMENT	Certificate authority not_after must be strictly after not_before.
2307005	CERTIFICATE_AUTHORITY_NOT_FOUND	NOT_FOUND	Certificate authority not found.
2307006	CERTIFICATE_AUTHORITY_ALREADY_EXISTS	ALREADY_EXISTS	A certificate authority with this name already exists in the workspace.
2307008	CERTIFICATE_AUTHORITY_PARENT_NOT_FOUND	NOT_FOUND	Parent certificate authority referenced by this intermediate does not exist.
2307010	CERTIFICATE_AUTHORITY_WORKSPACE_NOT_FOUND	NOT_FOUND	The workspace this certificate authority belongs to does not exist.
2307011	CERTIFICATE_AUTHORITY_TYPE_NOT_VALID	INVALID_ARGUMENT	Certificate authority type must be ROOT or INTERMEDIATE.
2307012	CERTIFICATE_AUTHORITY_IS_REVOKED	FAILED_PRECONDITION	Certificate authority is revoked and cannot issue new certificates.
2307013	CERTIFICATE_AUTHORITY_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Certificate authority must be marked for deletion before removal.
2307014	CERTIFICATE_AUTHORITY_IS_EXPIRED	FAILED_PRECONDITION	Certificate authority is expired and cannot issue new certificates.
2307015	CERTIFICATE_AUTHORITY_NOT_YET_VALID	FAILED_PRECONDITION	Certificate authority is not yet valid and cannot issue new certificates.
2307016	CERTIFICATE_AUTHORITY_STATE_NOT_VALID	INVALID_ARGUMENT	Certificate authority state must be ACTIVE, REVOKED, or EXPIRED.
2308001	CERTIFICATE_SERIAL_NOT_VALID	INVALID_ARGUMENT	Certificate serial is required and must be at most 128 characters.
2308002	CERTIFICATE_SUBJECT_NOT_VALID	INVALID_ARGUMENT	Certificate subject is required.
2308003	CERTIFICATE_VALIDITY_WINDOW_NOT_VALID	INVALID_ARGUMENT	Certificate not_after must be strictly after not_before.
2308004	CERTIFICATE_NOT_FOUND	NOT_FOUND	Certificate not found.
2308006	CERTIFICATE_ALREADY_REVOKED	FAILED_PRECONDITION	Certificate has already been revoked.
2308007	CERTIFICATE_ALREADY_TERMINAL	FAILED_PRECONDITION	Certificate is already in a terminal state and cannot be revoked.
2308008	CERTIFICATE_REVOCATION_REASON_NOT_VALID	INVALID_ARGUMENT	Certificate revocation reason must be a valid RFC 5280 reason.
2313001	CERTIFICATE_TEMPLATE_NAME_NOT_VALID	INVALID_ARGUMENT	Certificate template name is not valid.
2313002	CERTIFICATE_TEMPLATE_ALLOWED_DOMAINS_NOT_VALID	INVALID_ARGUMENT	Certificate template allowed_domains must contain at least one valid domain pattern.
2313003	CERTIFICATE_TEMPLATE_MAX_TTL_NOT_VALID	INVALID_ARGUMENT	Certificate template max_ttl must be positive and not exceed the parent CA validity remaining.
2313004	CERTIFICATE_TEMPLATE_ALLOWED_KEY_TYPES_NOT_VALID	INVALID_ARGUMENT	Certificate template allowed_key_types must contain at least one entry.
2313005	CERTIFICATE_TEMPLATE_ALLOWED_EXTENDED_KEY_USAGES_NOT_VALID	INVALID_ARGUMENT	Certificate template allowed_extended_key_usages must contain at least one entry.
2313006	CERTIFICATE_TEMPLATE_NOT_FOUND	NOT_FOUND	Certificate template not found.
2313007	CERTIFICATE_TEMPLATE_ALREADY_EXISTS	ALREADY_EXISTS	A certificate template with this name already exists for the certificate authority.
2313008	CERTIFICATE_TEMPLATE_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Certificate template is not marked for deletion.
2313009	CERTIFICATE_TEMPLATE_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Certificate template workspace ID is required.
2313010	CERTIFICATE_TEMPLATE_CERTIFICATE_AUTHORITY_NOT_FOUND	NOT_FOUND	The certificate authority this certificate template belongs to does not exist.
2313011	CERTIFICATE_TEMPLATE_DOMAIN_NOT_ALLOWED	INVALID_ARGUMENT	Requested certificate domain is not in the certificate template’s allowed_domains list.
2313012	CERTIFICATE_TEMPLATE_TTL_EXCEEDS_MAX	INVALID_ARGUMENT	Requested certificate TTL exceeds the certificate template’s max_ttl.
2313013	CERTIFICATE_TEMPLATE_KEY_TYPE_NOT_ALLOWED	INVALID_ARGUMENT	Requested certificate key type is not in the certificate template’s allowed_key_types list.
2313014	CERTIFICATE_TEMPLATE_EXTENDED_KEY_USAGE_NOT_ALLOWED	INVALID_ARGUMENT	Requested certificate extended key usage is not in the certificate template’s allowed_extended_key_usages list.
2314001	LOCATION_NOT_WELL_FORMED	INVALID_ARGUMENT	Location reference must be a valid identifier.
2314002	LOCATION_NOT_SUPPORTED	UNIMPLEMENTED	Only the global location is available in this release.
2315001	WORKSPACE_NOT_ACTIVE	FAILED_PRECONDITION	The workspace referenced by the request is not active.
2315002	WORKSPACE_TEARDOWN_FAILED	UNAVAILABLE	Failed to deprovision the vault backend for a deleted workspace.
2316001	VAULT_SNAPSHOT_FAILED	UNAVAILABLE	Failed to take a snapshot of the vault backend.
2316002	VAULT_RESTORE_FAILED	UNAVAILABLE	Failed to restore the vault backend from a snapshot.
2316003	VAULT_ROOT_KEY_ROTATION_FAILED	UNAVAILABLE	Failed to rotate the vault backend root key.
2317001	PLATFORM_SECRET_NOT_FOUND	NOT_FOUND	The platform secret path holds no entries.
2317002	PLATFORM_SECRET_PATH_NOT_VALID	INVALID_ARGUMENT	The platform secret path is outside the workspace key-value convention.
2318001	TAG_KEY_NOT_VALID	INVALID_ARGUMENT	The tag key is not valid.
2318002	TAG_VALUE_NOT_VALID	INVALID_ARGUMENT	The tag value is not valid.
2318003	TAG_KEYS_NOT_UNIQUE	INVALID_ARGUMENT	Tag keys must be unique within a resource.
2318004	TAG_COUNT_EXCEEDS_LIMIT	RESOURCE_EXHAUSTED	The resource carries too many tags.
2318005	TAG_TYPE_NOT_SETTABLE	INVALID_ARGUMENT	The tag type is server-managed and cannot be set by a client.
2319001	CAPSULE_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Capsule workspace ID is required.
2319002	CAPSULE_PAYLOAD_SIZE_NOT_VALID	INVALID_ARGUMENT	Capsule payload must be between 1 byte and 1 MiB.
2319003	CAPSULE_CONTENT_TYPE_NOT_VALID	INVALID_ARGUMENT	Capsule content type must be at most 255 characters.
2319004	CAPSULE_EXPIRY_NOT_VALID	INVALID_ARGUMENT	Capsule expiry must be after its creation.
2319005	CAPSULE_NOT_FOUND	NOT_FOUND	Capsule not found.
2319006	CAPSULE_ALREADY_ENDED	FAILED_PRECONDITION	This delivery has already ended and cannot be collected.
2319007	CAPSULE_REDEMPTION_SECRET_NOT_VALID	PERMISSION_DENIED	The redemption secret is not valid for this delivery.
2319008	CAPSULE_STATE_NOT_RECOGNISED	DATA_LOSS	The stored capsule state is not a recognised value.
2319009	CAPSULE_REDEMPTION_DIGEST_NOT_VALID	INVALID_ARGUMENT	Capsule redemption digest is required.
2319010	CAPSULE_NAME_NOT_VALID	INVALID_ARGUMENT	Capsule name must be a DNS label of 3 to 63 characters.
2319011	CAPSULE_WORKSPACE_NOT_FOUND	NOT_FOUND	Workspace not found.
2601001	VAULT_AUDIT_PAYLOAD_HASH_KEY_NOT_CONFIGURED	FAILED_PRECONDITION	The vault.audit.payload-hash-key property is required and must be set via the VAULT_AUDIT_PAYLOAD_HASH_KEY environment variable.
2605001	UNKNOWN_SCHEMA_VERSION	DATA_LOSS	Schema version is not recognized.
2606001	UNKNOWN_INTEGRATION_VERSION	INVALID_ARGUMENT	The integration version is not recognized.
2606003	UNKNOWN_TAXONOMY_EVENT	INVALID_ARGUMENT	The taxonomy event is not recognized.
2606004	UNKNOWN_MESSAGE_TYPE	INVALID_ARGUMENT	The message type is not recognized.
2606005	INTEGRATION_EVENT_FIELD_MISSING	INVALID_ARGUMENT	The integration event does not carry a required field.
2606006	INTEGRATION_EVENT_FIELD_NOT_VALID	INVALID_ARGUMENT	The integration event carries a field the reader cannot use.
2606008	RESTORE_SNAPSHOT_CHUNK_INVALID	INVALID_ARGUMENT	A restore snapshot chunk must contain between 1 byte and 1 MiB.
2606009	RESTORE_SNAPSHOT_STREAM_EMPTY	INVALID_ARGUMENT	The restore snapshot stream must contain at least one chunk.
2606010	RESTORE_SNAPSHOT_SIZE_EXCEEDED	RESOURCE_EXHAUSTED	The restore snapshot exceeds the maximum size.

Engine-selection failures

Vault validates the engines/{engine} path segment before it reaches an engine, and those refusals are argument errors rather than domain codes: a selector that names no configured engine, or the - wildcard on a request that requires a concrete one, is rejected with INVALID_ARGUMENT. The rules that decide which requests accept - are on engine selection.

When you read a federated result, do not infer a resource’s owner from the selector you sent. Use the engine field on the resource itself for any follow-up request.

Codes that are reported, not returned

None of these is ever a request’s error_code. They say why something further down refused, and they surface in one of two places: the errors list of an operation record, or the detail of the error actually returned, written as code:reason. Read them as the cause behind the status you were given.

Code	Reason	Description
2600001	ENGINE_UNREACHABLE	Vault engine is unreachable.
2600002	ENGINE_SEALED	Vault engine is sealed.
2600003	SERVICE_TOKEN_REJECTED	Vault engine rejected the privileged service token or denied it access.
2600005	MOUNT_OPERATION_FAILED	Vault engine mount operation failed.
2600006	PKI_ALGORITHM_NOT_SUPPORTED	Algorithm is not supported by the PKI engine.
2600007	PKI_PARENT_MOUNT_NOT_RESOLVABLE	Parent CA mount path could not be resolved.
2600008	PKI_LEAF_MOUNT_NOT_RESOLVABLE	Leaf certificate mount path could not be resolved.
2600009	RESOURCE_NOT_FOUND	Vault engine does not have the requested resource.
2600010	REQUEST_REJECTED	Vault engine rejected the request.
2600011	RESPONSE_NOT_READABLE	Vault engine returned a response the adapter cannot read.
2600012	RATE_LIMITED	Vault engine rate-limited the request.

Related

• Vault overview
• Engine selection
• Platform error model