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.
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).
PV1035	A user is only allowed to have one role. You can attach several capabilities and several policies to one role.
PV1036	The tenant isolation enforcement rule evaluation failed, and therefore the request was rejected.
PV1037	The action is not found. The only supported action is http_call.
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.
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.

Error codes related to control operations

Code	Details
PV2004	The property is not found
PV2005	The property name is invalid
PV2009	The property name is not unique
PV2010	The property's schema is invalid
PV2012	The property's data type is invalid
PV2013	One or more fields is too long
PV2014	One or more numeric fields is out of range
PV2015	The Admin user cannot be redefined
PV2016	One or more roles assigned to a user is not configured
PV2017	User name was not found
PV2020	The IAM configuration is invalid
PV2021	Regenerating a key for Admin is not allowed
PV2022	Configuration name is not supported
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
PV2026	The collection name is invalid
PV2027	Incorrect value type for configuration variable name
PV2028	The collection is invalid
PV2029	The collection already exists
PV2030	Failed to read one or more collections
PV2031	The specified collection type does not exist
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
PV2036	Update collection type is not allowed
PV2037	The collection's schema is invalid
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
PV2100	Unsupported change to an existing 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
PV2105	The bundle name is already in use
PV2106	Failed to delete the bundle
PV2107	Failed to find the bundle
PV2108	The bundle name is invalid
PV2109	The bundle has no compliant function exports
PV2110	The bundle does not compile
PV2111	The bundle has no exports
PV2112	The bundle function is missing or does not compile
PV2113	Prototype is missing
PV2114	Handler is missing on prototype
PV2115	Handler is not a function
PV2116	Function has the incorrect number of arguments
PV2117	The data type name is invalid
PV2118	The data type name is already in use
PV2119	Failed to delete the data type
PV2120	Failed to find the data type
PV2121	The bundle was not found
PV2122	The function is not exported 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 and cannot be deleted
PV2125	The bundle is in use by one or more collection 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
PV2129	The function name is invalid
PV2130	A built-in type cannot be deleted
PV2132	The update of a data type cannot add built-in transformers
PV2133	The sum of the collection and one of its property names is too large
PV2134	A collection-name_property-name combination is not unique
PV2135	is_index and is_unique are not supported for this data type
PV2136	The property type is invalid
PV2137	The admin API key is too short
PV2138	The admin API key is invalid

Error codes related to data operations

Code	Details
PV3002	One or more values is in a bad format
PV3003	One or more values is invalid
PV3004	Property does not exist
PV3005	One or more Objects IDs are not found
PV3006	One or more required unique fields is not unique
PV3009	One or more token IDs not found
PV3010	The token is invalid
PV3012	One or more token generation parameters is invalid
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.
PV3253	The value of an input field of data type EMAIL exceeded the maximum length.
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. This error happens if you
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. This error is most likely to occur for bad input format to the http_call action. See http_call request body for more details.
PV3263	Action invocation failed with an error. This error is most likely to occour for a template input or response, to the http_call action.
PV3264	The action role not configured in the IAM configuration. This error can occur if PVAULT_SERVICE_ACTIONS_HTTP_CALL_ROLE configuration for more details. is pointing to a non existent IAM role.
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.
PV3269	Query with no values is not allowed.
PV3270	Token update failed. See update-tokens API for the constraints that may fail this operation.

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.