Skip to main content

jsonAction response

List of properties in jsonAction response messages

Abstract

The following properties are part of each jsonAction response message.

The following properties are part of each jsonAction response message. All are optional except for "result", "errorCode", and "errorMessage". APIs often take advantage of the optional properties to implement advanced features.

Example

{
  "requestId": "1",
  "result": {},
  "errorCode": 0,
  "errorMessage": "",
  "debugInfo":
  {
    "request":
    {
      "requestId": "1",
      "authToken": "replaceWithValidAuthtoken",

      "action": "someAction",
      "params": {},

      "api": "someApi",
      "apiVersion": "1.0",

      "responseOptions": { },
      "debug": "max"
    },
    "serverSuppliedValues": {},
    "errorData": {},
    "warnings": [ { "warningCode": 0, "warningMessage": "", "warningData": {} } ],
    "executionPlan": {}
  }
}

Property summary

Table 1. Response message property summaries

Property

Description

Type

Limits (inclusive)

debugInfo

contains troubleshooting information about a request and its response

object

debugInfo
.errorData

contains data about an error

object

debugInfo
.executionPlan

contains data about the execution of a query

object

debugInfo
.request

contains all properties that can be included in an request

object

debugInfo
.serverSuppliedValues

contains zero or more properties set by the server to default values

object

debugInfo
.warnings

contains a warning object for each warning the server wants to communicate to the client

array of objects

errorCode

indicates an error when set to a non-zero integer or success when 0

integer

-2,147,483,648 to 2,147,483,647

errorMessage

contains a human-readable error message

string

0 to 256 bytes

requestId

contains any JSON value to identify a message as assigned by the client

string
number
object
array
Boolean
null

result

contains the result of an action

object



"debugInfo"

The "debugInfo" property is an optional, case insensitive string enum that causes the server to return no, a minimal, or a maximum amount of debug information in the response message. The default value is "none". The JSON is pretty printed for readability except when set to "none".

Possible values:

  • "none"

    This is the equivalent to omitting the "debug" property or setting to null.

  • "min"

    This causes the server to return a minimal amount of extra debugging information in the response message.

  • "max"

    This causes the server to return a maximum amount of debugging information in the response message which is useful for deep troubleshooting but requires significant computational power and resources for the server to generate this information. It is typically used during development and QA.

"errorCode"

The "errorCode" property occurs only in a response message. It is a signed integer from -2,147,483,648 to 2,147,483,647. A non-zero value indicates an error.

Essential information

  • When there is no error the value is 0.

  • When there is an error, it contains a non-zero integer number that uniquely identifies the cause of the error.

  • FairCom's error codes are listed in the error code reference.

Error codes

Table 3. Error codes from -32768 to -32000 are assigned specific meanings by the jsonAction specification

error.code

error.message

error.meaning

-32700

Parse error

This indicates an error occurred on the server while parsing the request.

-32600

Invalid request

This indicates the request message does not match the requirements of the specified version of the API.

-32601

Method not found

This indicates the action does not exist or is not available.

-32602

Invalid params

This indicates invalid action parameter(s). It occurs when a required property is missing or when an unexpected property is in the message.

-32603

Internal error

This indicates a unexpected jsonAction error.

-32000 through -32099

Server error

These are reserved for future jsonAction errors.



"errorMessage"

The "errorMessage" property is a string set by the server. It contains a human-readable error message.

Essential information

  • It is a zero-length string when there is no error.

  • It is a non-zero-length string that describes the error.

  • Look for a non-zero value in the "errorCode" property to know when there is an error.

"requestId"

The "requestId" property is typically a string or integer but can contain any JSON value that is an identifier assigned by the client. It is optional and defaults to null.

Essential information

  • "requestId" can contain any JSON value including:

    • object

    • array

    • string

    • integer

    • Boolean

    • null

  • From the client's perspective, "requestId" uniquely identifies a message where the server returns this identifier to the client in its response message. This allows a client to match a request to a response.

  • It is particularly useful when a client runs JSON DB API over an asynchronous protocol, such as MQTT or WebSocket.

  • It can be omitted or set to a zero-length string when the client does not need it.

"result"

The "result" property is a required object set by the server that contains the result of an action.

Essential information: