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

{
  "authToken": "serverSuppliedAuthTokenMayBeOptional",
  "requestId": "1",

  "result": {},

  "errorCode": 0,
  "errorMessage": "",

  "debugInfo":
  {
    "request":
    {
      "requestId": "1",
      "authToken": "serverSuppliedAuthTokenMayBeOptional",

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

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

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

Property summary

Table 1. Response message property summaries

Property

Description

Type

Limits (inclusive)

"debugInfo"

contains troubleshooting information about a request and its response

object

"errorCode"

determines if there is an error

integer

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

"errorMessage"

contains a human-readable error message

string

Minimum length: 0 bytes

Maximum length: 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 returned in a response when the "debug" property in a request is set to a value other than "none" or null. See "debug".

    "debug": "max"

"debugInfo": 
{
  "request": {
    "requestId": "1",
    "authToken": "uniqueServerSuppliedAuthToken",
    "api": "someApi",
    "apiVersion": "2",
    "action": "actionName",
    "params": {},
    "responseOptions": {},
    "debug": "max"
  },
  "apiVersion": "2.0.3",
  "serverSuppliedValues": {},
  "errorData": {},
  "warnings": [
    {
      "warningCode": 0,
      "warningMessage": "",
      "warningData": {}
    }
  ]
}

Property summary

Table 2. "debugInfo" response property summaries

Property	Description	Type
`"errorData"`	contains data about an error	object
`"request"`	contains all properties that can be included in an request	object
`"serverSuppliedValues"`	contains zero or more properties set by the server to default values	object
`"warnings"`	contains a warning object for each warning the server wants to communicate to the client	array of objects

`"errorData"`

The "errorData" property is an object. An API defines the data it puts in this property when there is an error.

Things to know:

If there is no additional data, it is an empty object.
Its properties may vary with the API, action, and error message.

`"request"`

The "request" property contains the original values submitted in the request. It is included when the "debug" property is set to "max". See Request.

"request": 
{
  "authToken": "serverSuppliedAuthTokenMayBeOptional",
  "requestId": "1",

  "api": "someApi",
  "apiVersion": "1.0",
  "action": "deleteSession",
  "params": {},

  "responseOptions": {},
  "debug": "max"
}

`"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.

Things to know:

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.

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.

Things to know:

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.

Things to know:

"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. Its properties vary with each action.

{
  "authToken": "anAuthorizationTokenFromTheServer",
  "requestId": "1",
  "result": 
  {
    "data": 
    [
      {
        "id": 3,
        "name": "Muhammad Ali",
        "birthDate": "1942-01-17",
        "favoriteSaying": "Float like a butterfly, sting like a bee."
      }
    ],
    "moreRecords": false
  },
  "errorCode": 0,
  "errorMessage": ""
}

In this section:

jsonAction.org