Error Handling
When an error occurs, Vault Server will return error messages in the response body. The response body structure for errors is usually in JSON format.
Vault Server REST API Errors
Errors generated by the Vault Server REST API typically return a 4xx HTTP status code in the response header. The response body provides details of the error. The body structure of the error response for Vault Server REST API errors is as follows:
statusCode number | The HTTP status code that was reported in the response header. |
errorCode string | A code that identifies the error type, please refer to Vault Server error codes for more detail. |
title string | A summary of the error, suitable for use as a title. |
detail string | A short, human-readable explanation of the error. |
params array of string | Additional information about the error, if available. |
Example
{
"statusCode": 400,
"errorCode": "301",
"title": "Vault error",
"detail": "The user name and/or password appears to be invalid; please try again.",
"params": []
}
{
"statusCode": 400,
"errorCode": "155",
"title": "Vault error",
"detail": "Illegal null parameter passed to server.",
"params": []
}
{
"statusCode": 401,
"errorCode": "8000",
"title": "Vault error",
"detail": "You currently do not have permissions to download this file. Contact your admin for support.",
"params": []
}
{
"statusCode": 404,
"errorCode": "5004",
"title": "Vault error",
"detail": "Resource is not found for the given id dABlAHMAdAA_.",
"params": [
"dABlAHMAdAA_"
]
}
Additional Information
Some APIs provide additional information in the error response headers.
HEAD /vaults/{vaultId}/file-versions/{id}/content
Header | Type | Description |
---|---|---|
x-vault-error-code | string | Vault error code for the specific error that occurred. |
x-vault-error-code | string | A brief, human-readable description of the error. |
Exceptions
If you are using the Vault Gateway to connect to the Vault Server, the gateway sometimes returns other types of error messages, such as 429 errors for rate limiting. For more information about rate limiting, see Rate Limits and Quotas.
If requests violate Vault Gateway restrictions or the Vault Gateway service encounters errors, you may see Vault Gateway related errors in the response. Please refer to the Vault Gateway documentation for more information.