The VESvault REST API at https://api.ves.host/v1/ reports every failure as one or more numbered error entries. This page explains the response format and lists every error number the API returns.

Most applications call the API through libVES.js, libVES.c or the ves command line utility, which pass the number through to you.

A failed request returns a JSON object with an errors array:

{
    "errors": [
        {
            "code": "NotFound",
            "number": 4021,
            "message": "Object does not exist"
        }
    ]
}

Some errors add more members, described with the error. Expect members not listed here and ignore the ones you do not use.

A POST can return several entries at once, one for each invalid field. The HTTP status of the response comes from the first entry.

A few errors are sent next to a result (1061, 9011). In that case the result is real but incomplete, and the error says what is missing.

Every error number has four digits. The first digit is the error class, which also sets the HTTP status:

The second digit usually names the kind of object involved: 0 – the request or session, 1 – user, 2 – Vault Key, 3 – Vault Item or file, 5 – Vault Entry, 7 – domain, 9 – external reference. For example, 5291 is an AccessDenied error (5) on a Vault Key (2).

• 1xxx Internal – a failure on the server, expected to be temporary. Retry the request with an increasing interval. If it keeps failing, report the error with its number.
• 2xxx BadRequest, 7xxx InvalidData – the request needs to be fixed. Do not retry it unchanged.
• 3xxx Unauthorized – authenticate again. 3014 means the session has expired.
• 4xxx NotFound – the object named in the path or in the posted body does not exist. Check the ID.
• 5xxx AccessDenied, 6xxx ReadOnly – the session is not allowed to do this. A different session or a different operation is needed. Retrying will not change the answer.
• 8xxx OverQuota – come back later. Retry with an increasing delay.
• 9xxx TooLarge – ask for less: fewer fields, or a range on the list named by path. Retrying the same request will get the same answer.

libVES.js rejects the promise with a libVES.Error built from the first entry. The entry's members are copied onto the error, so err.code, err.number, err.message and err.path are available. Set an onerror handler to receive all entries.

VES.get('vaultItems/12345').catch(function(err) {
    if (err.number == 4021) {
        // no Vault Item with this ID
    }
});

libVES.c maps the HTTP status to a LIBVES_E_* code: 401 and 403 become LIBVES_E_DENIED, 404 LIBVES_E_NOTFOUND, 503 LIBVES_E_QUOTA, and any other status LIBVES_E_SERVER. The error number is in the message from libVES_getErrorInfo(), which starts with API# and the number, for example API#4021: HTTP 404.

The ves utility prints that message and exits with the libVES error code, as listed in its Exit Codes.

Each error is listed with the message the server sends, followed by what it means. A … in a message stands for text that varies.

Internal errors are expected to be temporary and every one of them can be retried. Retry with an increasing interval, and report the error with its number if it keeps failing.

Each request is charged against several budgets: the caller's network address, and where they apply the user, the domain and the app. When one runs out, the API answers 503 until it refills. The last three digits name the budget. The entry also carries sel, naming the meter that ran out, and ref. Include both if you contact support.

The same budgets can be switched off by VESvault. That is reported as AccessDenied with the matching number (5001, 5101, 5701, 5901) and the message Administratively disabled: …, and is not resolved by waiting.

The API caps how many rows one request reads and how large one response can be. To page through a list, put a range after the list field in fields: [start+count], as in vaultItems(id,type)[0+100]. start is an object ID, not a position: the list returns up to count objects whose ID is start or higher, in ID order, and 0 starts from the beginning. The response carries a ranges entry for the list with nextId; ask for [nextId+100] to get the next page, and stop when more is false. Use - in place of + to go the other way, from start down to lower IDs ([0-100] is the 100 highest IDs).