Error Handling
When an error occurs, Vault Server returns error messages in the response body. The response body for errors is 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. See Vault Server error codes for details. |
| 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. |
Examples
{
"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-detail | string | A brief, human-readable description of the error. |
Exceptions
When connecting through the Vault Gateway, you may receive additional error types not generated by the Vault Server. For example, the gateway returns HTTP 429 errors when your application exceeds the rate limit.
If a request violates gateway restrictions or the gateway encounters an internal error, the response will contain a gateway-specific error. See the Vault Gateway documentation for details.