In regular responses, the JSON response is an array of objects where each member gives information about how a particular command executed. Any time there is an error, the JSON response returned will not be an array but a JSON object with a member “status”. So a check to see whether status is a member of response should reveal whether there was an error or not.

Responses for all the Find* commands indicate if “blob” was set to true or false when requesting results. If “blob” is true, there is an additional variable “blob_start” which gives the 0-based vector index for where the first blob corresponding to that command is placed in the return vector. In case of FindEntity, even if “blob” is true, not all entities have a blob associated with them. Therefore, “_blob” (_ is to avoid clashing with potentially a property within entity named blob) being true or false is embedded along with the property values list.

Return Status

Each call returns a “status” with an integer value listed with its meaning in the table below. 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.

Return Value Status Description
0 Success The command was successful
1 Empty A search query returned no results
2 Exists A conditional add found a unique instance of an existent object.
3 NotUnique A search query specified “unique” = true but got multiple results.
-1 Error There was an error, the “info” field should provide a message.

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


# Successful AddEntity

"AddEntity" : {
    "status": 0

# 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" ]