Returned Status¶

Each call returns a status with an integer value. In case a command is unsuccessful, we return an error code and provide information on why it failed using the info field.

However, if there is a local id provided in such a call, we treat it as an exception which causes the rest of the transaction to abort. This is necessary to avoid relying on calls that were not successful. When a transaction aborts, it undoes all the metadata changes that were made until the point where the error occurred.

Status Codes¶

The following table provides status codes and their meanings.

Return value	Status	Description
0	Success	The call was successful and performed as expected.
1	Empty	A search query returned no results.
2	Exists	A conditional add found a unique instance of the entity to exist already. If not unique, an error (-1) is returned depending on absence/presence of `_ref` in the call.
3	NotUnique	If a search query wanted a unique entity but has multiple results. An error (-1) is returned depending an absence/presence of `_ref` in the call.
-1	Error	There was an error and the error message indicates what occurred.

If every command within a transaction succeeded, VDMS will return one JSON object with the corresponding status code and possible results information. If any of the commands fails, VDMS will return a single JSON object indicating the error status, information about what caused the failure, and the command that caused the failure.

Success Example¶

// Successful AddEntity
"AddEntity" : {
    "status": 0
}

Failed Example¶

// FindEntity with using a wrong "ref"
"FindEntity" : {
    "status": -1,
    "info": "Reference does not exist",
    "FailedCommand": {
        "FindEntity": {
            "_ref": 344554,
            "class": "patient",
            "constraints" : {
                "bcr_patient_barc": [ "==", "TCGA-02-0070" ]
            }
        }
    }
}