.. _responses: 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 :doc:`API-Description` for input and output blob ordering and :doc:`parameters/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 :doc:`parameters/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 ------------- .. list-table:: :header-rows: 1 :widths: 12 22 66 * - 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 :doc:`parameters/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 :doc:`ConfigFile`. * - 5 - SchemaError - A write conflicts with the schema, for example a conflicting property type. Inspect :doc:`commands/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 :doc:`HandlingOfMissingData` for missing-value comparisons. .. _response-error-phases: 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. .. list-table:: :header-rows: 1 :widths: 30 70 * - 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 :doc:`TransactionsAndReferences`. 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. .. TESTED_EXAMPLE: Responses_1 .. code-block:: json [ { "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 :doc:`commands/FindImage` and :doc:`commands/FindEntity`. Their reference-only lookups illustrate why ``returned: 0`` does not always mean zero matches.