REST API error codes

The Piiano Vault REST API has error codes for every error condition. These codes are returned as part of the error message from the REST API and are written to the logs.

Vault error codes

This table contains all the error codes returned by the Vault REST API. Let us know if you require further details or clarifications for an error code.

Code	Details
PV1000	Server error. Vault logs may indicate the source of the issue. Contact Piiano if the problem persists. With the default configuration, these errors are sent to Piiano for investigation.
PV1001	Access reason must be provided as a query parameter unless the environment variable PVAULT_SERVICE_FORCE_ACCESS_REASON is set to false.
PV1002	The access reason is invalid. Follow these guidelines on how to set the access reason.
PV1004	The collection doesn't exist or the caller has insufficient permissions to view the collection.
PV1005/PV1006/PV1007	To debug authorization failures use pvault iam resource-view and pvault iam user-view. To identify if your token has expired, run pvault iam get-user. For JWT related errors, see JWT specific error messages.
PV1008	The collection name is invalid. Follow the naming conventions for entities.
PV1009	The operation timed out. There is a built-in timeout of 30 seconds for every API call. For object operations, check for missing indices in your pvschema. For token operations, check whether you are trying to retrieve too many tokens in one operation.
PV1010	Vault can't connect to its database. Inspect your database configuration. Unless you are running stateless mode, Vault can not function without a reliable database connection.
PV1011	You can enable and disable users as part of the IAM configuration. Once disabled you can not initial calls for this user.
PV1012	The request could be invalid if it does not comply with the OpenAPI specification. The error context should contain details of the offending field.
PV1013	Your license has expired. If you are a paying customer, contact Piiano. Anyone can get a free 7-day trial license from the get started section of the Piiano documentation.
PV1014	More than one caller attempted to access the same resource as updaters, resulting in a potential conflict. For example, trying to update the same object twice from two callers in parallel.
PV1015	Due to caching of the collection schema, subsequent deletion of a collection and access to it from different threads may return this error.
PV1025	Supported content-types are: application/json and in specific calls that support it: application/toml and application/pvschema.
PV1026	Stateless mode only supports some operations. Did you intend on running stateless mode? Check the stateless mode guide for more information.
PV1027	Javascript is enabled by default. Check if you disabled it using the environment variable PVAULT_FEATURES_DISABLE_JAVASCRIPT.
PV1028	You can not dynamically modify the IAM when it is configured to load at startup with the environment variable PVAULT_SERVICE_SET_IAM_ON_START_ONLY.
PV1029	This error can occur in an AWS environment where the authentication session to the KMS has expired. Check the Vault's AWS role and IAM permissions to access the KMS.
PV1030	The request contains an invalid UTF-8 sequence.
PV1031	The size of a property being indexed exceeds the maximum allowed size for an index entry in PostgreSQL. Either remove an INDEX from your schema or contact us to work around this issue
PV1032	Conflict with another concurrent operation to the same resource. This can happen if you try to update the same piece of data from two different threads in parallel.
PV1034	A collection being accessed is unavailable. It could occur when using multiple Vault instances, deleting a collection from one instance, and trying to access it from another instance in parallel (or before the cache is synced - up to 30 seconds).
PV1036	The tenant isolation enforcement rule evaluation failed, and therefore the request was rejected.
PV1037	The action is not found.
PV1038	A request sent from a browser was rejected due to your CORS policy. You need to configure the PVAULT_SERVICE_ALLOW_ORIGINS to allow the origins creating these browser requests.
PV1039	The action role not in the IAM configuration. This error occurs if the PVAULT_SERVICE_ACTIONS_HTTP_CALL_ROLE environment variable is pointing to a non-existent IAM role.

Error codes related to control operations

Code	Details
PV2001	This operation is not implemented. For example, when calling with the wrong HTTP method, e.g., calling the version endpoint with the method PATCH instead of GET.
PV2002	Anti-tampering has been triggered. It could happen if you manually modified your database (which you should not) or restored the database from a snapshot that is incompatible with the Vault's version. See the anti tampering guide for more details.
PV2003	Some Vault instances are not synced. Try again in 30 seconds. Use the pvault system cluster-info CLI command to see the status of other Vault instances. See Cache refresh rate guide for more details.
PV2004	The property does not exist in the collection.
PV2005	The property name is invalid. For more information: Add collection property.
PV2009	The property name is not unique. There is already a property with the same name in the collection.
PV2010	The property's schema is invalid. it should comply with PVSchema format
PV2012	The property's data type is invalid. Property type is one of builtin data types or custom data types
PV2013	One or more fields is too long. For more information: Add collection property.
PV2014	One or more numeric fields is out of range
PV2015	The Admin user cannot be redefined. Admin user is predefined by Vault.
PV2016	No role is configured for the role name.
PV2017	User name was not found. Use Get IAM to list users.
PV2020	The IAM configuration is invalid. For more information How IAM works.
PV2021	Regenerating a key for Admin is not allowed.
PV2022	Configuration name is not supported. For more information: Set configuration variable.
PV2023	The URL property name: url_property_name and body property name: body_property_name don't match.
PV2024	The specified collection does not exist. Use List collections to check for existing collections.
PV2026	The collection name is invalid. For more information Add collection.
PV2027	Incorrect value type for configuration variable name. For more information: Set configuration variable.
PV2028	The collection is invalid. For more information: PVSchema format.
PV2029	The collection already exists.
PV2030	Failed to read one or more collections.
PV2031	The specified collection type does not exist. For more information Add collection.
PV2032	A built-in property cannot be deleted.
PV2033	A built-in property cannot be added.
PV2034	A built-in property was provided with incorrect fields.
PV2035	Update collection name is not supported. For more information Update collection.
PV2036	Update collection type is not allowed. For more information Update collection.
PV2037	The collection's schema is invalid. For more information: PVSchema format.
PV2038	A non nullable property can't be added while the collection is not empty.
PV2039	The new bundle functions are not a superset of the current bundle functions. For more information Update bundle.
PV2100	Unsupported change to an existing property. For more information Update collection property.
PV2101	A built-in data type cannot be updated.
PV2102	A custom data type that is in use cannot be deleted.
PV2104	A JavaScript method failed to compile. For more information: Bundles.
PV2105	The name is in use. See Naming rules for more details.
PV2106	Failed to delete the bundle.
PV2107	Failed to find the bundle. Use List bundles to list existing bundles.
PV2108	The bundle name is invalid. For more information: Bundles.
PV2109	The bundle has no compliant function exports. For more information: Bundles.
PV2110	The bundle does not compile. For more information: Bundles.
PV2111	The bundle has no exports. For more information: Bundles.
PV2112	The bundle function is missing or does not compile. For more information: Bundles.
PV2113	Prototype is missing. For more information: Bundles.
PV2114	Handler is missing on prototype. For more information: Bundles.
PV2115	Handler is not a function. For more information: Bundles.
PV2116	Function has the incorrect number of arguments. For more information: Bundles.
PV2117	The data type name is invalid. For more information: Add data type.
PV2119	Failed to delete the data type. Use List data types to list existing data types.
PV2120	Failed to find the data type. Use List data types to list existing data types.
PV2121	The bundle was not found. Use List bundles to list existing bundles.
PV2122	The function is not exported by the bundle. Should be expored by the bundle.
PV2123	The base type of a data type must be a built-in type
PV2124	The bundle is in use by one or more data types or actions, and cannot be deleted.
PV2125	The bundle is in use by one or more collections and cannot be deleted.
PV2126	The default transformer is not in the transformers list.
PV2127	The license is invalid. Please contact support.
PV2128	The license is missing. License should be set via env var or Set license.
PV2129	The function name is invalid. For more information: Bundles.
PV2130	A built-in type cannot be deleted.
PV2132	Failed to update data type.
PV2133	The sum of the collection and one of its property names is too large. The length of the combination of both should not exceed 41.
PV2134	A collection-name_property-name combination is not unique.
PV2135	is_index and is_unique are not supported for this data type because its max length exceeds 2048.
PV2136	The property type is invalid. Property type is one of builtin data types or custom data types
PV2137	The Admin API key is too short. For more details Set Admin API key.
PV2138	The Admin API key is invalid. The new API key should be at least 15 characters long, and have a lowercase latin character, uppercase latinc character, and a digit.
PV2139	is_substring_index is not supported for this data type or configuration. See indexing in the data type reference for a list of supported data types.
PV2140	The data type is restricted in PCI. This error can occur if PCI restrictions are enabled. See the Accessing section of the PCI guide for more details.
PV2141	Deleting a built-in action is not allowed.

Error codes related to data operations

Code	Details
PV3002	One or more values is in a bad format. See data-type validations for more details.
PV3003	One or more values is invalid. This is most likely due usage of a wrong type for a property (e.g. an integer when expecting a string). See data-type for more details.
PV3004	Property does not exist.
PV3005	One or more Objects IDs are not found.
PV3006	One or more of the values provided to a unique property already exist.
PV3009	One or more token IDs not found.
PV3010	One or more columns does not exist. This is probably due to a change in schema using a Control operation. Please wait for the cache to refresh.
PV3013	One or more required fields is missing or null.
PV3014	One or more string values exceeded max length.
PV3015	One or more numeric values is out of range.
PV3016	Original property doesn't exist.
PV3020	Failed to parse object ID.
PV3021	Specify Props or Unsafe but not both.
PV3022	Specify one of Props or Unsafe.
PV3023	The specified collection does not exist.
PV3024	The collection name is invalid.
PV3025	The property name is invalid.
PV3026	Cannot set an owner for a PERSON object.
PV3027	Owner ID is invalid.
PV3028	Shouldn't provide _tenant_id when owner is specified.
PV3029	Must specify owner ID and owner collection or specify neither.
PV3030	Owner collection is not found.
PV3031	Owner ID is not found.
PV3032	Owner collection is not valid.
PV3033	DATA object owner can be PERSON object only.
PV3034	Non nullable property must not be null.
PV3035	The number of object IDs is greater than the maximum page size.
PV3036	ID must exist in update objects field.
PV3037	Invalid ID.
PV3038	The number of objects is greater than the maximum page size.
PV3079	Cannot add readonly properties.
PV3081	The query should not be empty.
PV3084	Property with transformation is not supported for query.
PV3085	Cannot update this property.
PV3086	The token is irreversible.
PV3088	Format preserve template does not exist.
PV3089	Format preserve template requires a different number of properties.
PV3090	Format preserve template requires property of a different type.
PV3091	Missing token query params. Use tags, token ID, or object ID.
PV3092	Missing token ID params.
PV3093	One or more token rotation parameters is invalid.
PV3100	A transformer is not found for the property.
PV3101	Multiple properties per transformer is not implemented.
PV3203	Too many tags provided.
PV3204	At least one update params required.
PV3205	Query param option show_builtins is only available if unsafe option is requested.
PV3206	Query param page_size exceeds the maximum value allowed. See api-pagination for more details.
PV3207	Query param option page_size is only available when IDs are not provided.
PV3208	Cannot create an object with an expiration duration of 0 seconds.
PV3210	Failed to parse the cursor. This error most likely to occur of the cursor used in the request is not the exact value returned by Vault in an earlier response. Check that the value provided in the cursor parameter matches Vault's previous response.
PV3211	The number of items requested exceeds the maximum value allowed
PV3213	Archived object's properties cannot be modified. You can only set its expiration to a new value.
PV3214	Archived tokens cannot be updated. You can only set its expiration to a new value.
PV3215	Archived tokens cannot be detokenized. Restore the token first to be able to detokenize it. See Object lifecycle for more details.
PV3216	Cannot tokenize an object with an expiration duration of 0 seconds.
PV3217	Custom validation failed. This means that the JS validator configured for your Data Type has returned a negative value.
PV3219	A runtime error occurred in a JavaScript method.
PV3221	Tokenize Blob data type is allowed only as type pointer.
PV3222	Token for the property does not exist. You can only use the Token transformation for already existing tokens.
PV3223	Rotating an irreversible token is not allowed. This error most likely to occur when trying to rotate a type pci_oneway token. See Token types for more details.
PV3230	Pointer token is only allowed on an existing or new object. When providing the input_object parameter, make sure to either use the id field, or other fields alongside store_object turned to "true".
PV3231	The requested property value was missing from the input object. Make sure that the props parameter is a subset of the input objet fields.
PV3232	Cannot tokenize an object with empty fields. This error occures when passing an empty fields in the input object parameter.
PV3233	The encrypted object is archived. This error most likely to occur if the encrypted object is archived, but the archived option is not set. See Decrypt for more details.
PV3234	Deterministic encryption with expiration is not allowed.
PV3236	Invalid ciphertext. This error most likely to occur if the ciphertext provided as an input, ether as part of an input object, or to operation like Decrypt, is invalid. Make sure to use the exact value you got from Vault as from an Encrypt operation.
PV3237	The encrypted object is active. This error most likely to occur if the encrypted object is active, but the archived option is set. See Decrypt for more details.
PV3238	Object ID is not allowed in stateless mode. Use other input options such as fields or ciphertext.
PV3239	Value is not a valid UUID. This error most likely to occur if a non UUID external object ID is provided when adding an object. See add-object for more details.
PV3241	The transaction ID is invalid. Valid values are of of length less than 256.
PV3242	The transaction ID is not found.
PV3243	Transaction ID already exists for the given collection and entity.
PV3244	Decryption parameter is invalid. This error most likely to occur if the provided ciphertext is not as returned from Vault, or the scope provided to the operation does not match the scope provided to Encrypt Make sure to use the exact value you got from Vault as from an Encrypt operation, and the same scope.
PV3245	The data type of the property is invalid. Use an existing Data type.
PV3246	The data type of the property is invalid because it uses JavaScript, which is disabled. See PVAULT_FEATURES_DISABLE_JAVASCRIPT configuration for more details.
PV3247	Tokenize request with store object request without input object fields.
PV3248	Invalid input object request index out of range. Make sure that request_index field of the object parameter is positive and not greater then the length of the array of objects.
PV3249	Invalid input object request index to itself. Make sure that request_index field of the object parameter points to a different object in the array, or use a different input such as id, fields, or ciphertext.
PV3250	Invalid input object request index to other index. Make sure that request_index field of the object parameter doesn't point the another object that uses request_index.
PV3251	Token tag is longer than 256. Use a shorter tag.
PV3252	Property with transformation is not supported for export. The export parameter is intended to be used by the CLI command pvault export. See Data import and export for a detailed guide about import-export.
PV3254	Export key set does not exist. This error most likely to occur if trying to export but neither PVAULT_KMS_EXPORT_URI nor PVAULT_KMS_EXPORT_SEED are not configured. See Export data for more details.
PV3256	Export key is invalid. This error most likely to occur if you use the export_key or import parameters manually. Those parameters are intended to be used by the CLI command pvault import. See Data import and export for a detailed guide about import-export.
PV3257	Query param export_key is only available if query param import is true. This error most likely to occur if you use the export_key or import parameters manually. Those parameters are intended to be used by the CLI command pvault import. See Data import and export for a detailed guide about import-export.
PV3258	Expecting values to be encrypted when export_key is provided.
PV3259	Unique tags violation. This means that some tags were provided, and marked as ensure_unique_tenant_tags, are not unique in the Tenant level as supposed to.
PV3260	Unique tags are not included in tags. Make sure that the ensure_unique_tenant_tags input is a subset of tags. See Tokenize body for more details.
PV3261	Tenant can't contains commas. See Tenant isolation header for more details about the format.
PV3262	Invalid action input. When using the http_call action, refer to http_call request body for more details.
PV3263	Action invocation failed with an error. When using the http_call action, refer to http_call request body for more details.
PV3265	Expiration exceeded for field of datatype. This error can occur if PCI restrictions are enabled. See PCI - Property data types for more details.
PV3266	Provided token ID is invalid. See tokenize API (token_id input) for the constraints of this variable.
PV3267	Token ID cannot be provided if format preserving template is provided.
PV3268	Restricted data type for token type in PCI. This error can occur if PCI restrictions are enabled. See the Accessing section of the PCI guide for more details.
PV3269	Query with no values is not allowed.
PV3270	Token update failed. See update-tokens API for the constraints that may fail this operation.
PV3271	Enforcement is not supported for this endpoint. See Direct JWT configuration for more details.
PV3272	Enforcement does not support the data type. See Direct JWT configuration for more details.
PV3273	The property is not substring indexed. See Substring Search for more details.
PV3274	The collection is not synced to the substring cache. Wait for the next sync. The refresh interval is configured by environment variable PVAULT_SERVICE_SUBSTRING_INDEX_REFRESH_INTERVAL.
PV3275	The substring query pattern is too short. Must have at least 2 trigrams. See Search Patterns for more details.
PV3276	Token export failed.
PV3277	Token import failed.

PostgreSQL specific codes

Vault can return the underlying SQLSTATE error, which can assist in investigating an error case. The format of these errors is (SQLSTATE XXXXX). You can look up 5-digit code in the PostgreSQL error list.

JWT specific error messages

Code	Message	Diagnose
PV1005	jwt is probably corrupted or in the wrong format	Is the JWT actually a JWT or a different format like API key?
PV1005	jwt is probably signed with the wrong key	Is the IAM configuration up to date? Is the keys or jwks_uri up to date with the expected key pair? Is the JWT signed with the correct key?
PV1005	failed to find key with key ID	Is the kid claim of of the JWT matching the keys or jwks_uri configurations in the IAM configuration?
PV1005	audience does not match	Is the aud claim of the JWT matching the aud configuration in the IAM configuration?
PV1005	issuer does not match	Is the iss claim of the JWT matching the iss configuration in the IAM configuration?
PV1005	missing claim	Are all claims required by the bound-claims set in the JWT?
PV1005	bound claim does not match	Are the claims in the JWT matching the bound-claims set in the JWT?