Responses

A query returns JSON plus a separate list of binary blobs. Successful command results normally form an array in query order. Errors can instead be a top-level object, an error object inside a one-element array, or a failure inside a command result. Check every returned status and its info message; checking only for a top-level status misses command failures.

See API Description for input and output blob ordering and _ref and ref for references between commands.

Field Descriptions

• status is the integer result code. It is present in each command result and in a top-level error object.

• info describes an error or supplies command-specific information. Exact messages can include a command number or resource name.

• code identifies certain errors independently of their message. A top-level status: -1 with code: "unauthenticated" means the supplied session was rejected and no database changes were committed. Authenticate again, or use a newer token from the same session if another request already refreshed it. Permission refusals do not carry this code.

• returned counts returned objects or blobs for Find commands. It is not a universal match count and is not present on every kind of command. A Find that retains _ref without requesting properties can return 0 even when it matches objects. Request results: {"count": true} for a count.

• entities / connections contain requested property values. They can be omitted when no property payload is requested. Grouped results have the structure described in group_by_source.

• blobs_start is the zero-based index of this command’s first returned blob in the query’s complete output blob list. It is present when blobs are actually returned; an empty result need not contain it.

• _blob_index associates a returned object’s metadata with an index in that same complete output blob list. It is not relative to blobs_start.

Return Status

Value	Status	Meaning and next step
0	Success	The command succeeded. A Find with no matches also succeeds.
1	Empty	AddConnection resolved its source or destination to no objects, so no connection was created. Its info is Connection is not created: src and dst must have positive node counts. Check the endpoint searches.
2	Exists	A conditional add found an existing object. Inspect the command’s info and if_not_found before retrying.
3	NotUnique	A count expectation failed, for example a unique: true lookup that matches multiple objects. Other count requirements can also produce this code; use info to identify the condition.
4	ExcessiveSize	The response exceeds the configured message budget. Reduce the result page, return fewer properties, or omit/reduce blobs. The native default is 256 MiB; see Configuration File.
5	SchemaError	A write conflicts with the schema, for example a conflicting property type. Inspect GetSchema and correct the write.
-1	Error	Validation, permission, execution, or other failure. Use info and the command reference to correct the cause.

A missing class or property in a search does not itself produce status 1. See Handling of Missing Data for missing-value comparisons.

Failures and retrying writes

Graph, user, role, session, and credential changes succeed or roll back together. An error can also occur after those changes have been saved, while retrieving requested media or returning the response.

Failure	State and recovery
Invalid input or rejected authentication	The query has not changed the database. Correct the request or authenticate again.
A command fails before the transaction completes	The transaction’s changes roll back together. Correct the reported cause before retrying.
Requested media cannot be retrieved	Writes may already have succeeded. Check the affected data, users, roles, or credentials before retrying a query that also makes changes.
The response is too large, incomplete, or lost	The failure does not establish rollback. Reconnect and verify which changes succeeded before retrying missing work.

Errors may appear as a top-level object, a one-element error array, or a command-wrapped error. Inspect status and info at the reported level. Use stable application identifiers and conditional adds when retrying writes. A read-only request can usually be retried after correcting its cause, although results may change between reads. See Transactions and references.

Examples

This illustrative response shows two image lookups in one query. Blob indexes continue across commands. The separate binary output list contains five images; this JSON contains only their metadata and positions in that list.

[
  {
    "FindImage": {
      "blobs_start": 0,
      "entities": [
        { "_blob_index": 0, "id": 0 },
        { "_blob_index": 1, "id": 2 },
        { "_blob_index": 2, "id": 4 }
      ],
      "returned": 3,
      "status": 0
    }
  },
  {
    "FindImage": {
      "blobs_start": 3,
      "entities": [
        { "_blob_index": 3, "id": 1 },
        { "_blob_index": 4, "id": 3 }
      ],
      "returned": 2,
      "status": 0
    }
  }
]

For executable request/response pairs, see FindImage and FindEntity. Their reference-only lookups illustrate why returned: 0 does not always mean zero matches.