Response format

type: object

Properties

Name	Type	Presence	Description
jsonrpc	string("2.0")	Always	Will always be "2.0".
id	any	Always	The client-side ID used for the request.
result	Result	On success	The result of a successful method call. In Clarify, the return type is always an object. The exact structure of the object depend on the method that was called.
error	Error	On failure	The result of a failed RPC method. In Clarify, we define our own structure for the error data field.

response body example

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {...}
}

response body example (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "trace": "00000000000000000000",
      "params": {
        "integration": ["required"]
      }
    }
  }
}

Result

type: object

In Clarify, the result of an RPC request is always an object. The exact keys that are present depend on the method that was called and the parameters that where provided. If a result is present, it means the call succeeded.

Error

Error describe the standardized JSON RPC 2.0 error format, as well as a clarify specific data field and error codes. When an error is present, the result portion will be empty.

type: object

Parameters

Name	Type	Require	Description
code	integer	Yes	A code describing the error type.
message	string	Yes	A textual description of the error.
data	Error Data	No	An object describing more details related to the error. The structure of the ErrorData object is Clarify specific.

Error Data

Error Data is a Clarify specific format for embedding useful error information.

type: object

Name	Type	Presence	Description
trace	string	Always	A unique ID that can be supplied to the Clarify Support team to help us debug what happened for a particular failed request.
params	map of string => array of string	Optional	Present when the error code and message can be traced back to specified parameters.

Error codes

JSON RPC standard error codes:

Code	Name	Description
-32700	Parse error	Invalid JSON was received by the server.
-32600	Invalid request	The JSON sent is not a valid Request object.
-32601	Method not found	Method does not exist / is not available.
-32602	Invalid params	Invalid method parameter(s).
-32603	Internal error	Internal JSON-RPC error.
-32000 - -32099	Server error	Reserved for implementation-defined server-errors.

Clarify specific error codes:

Code	Name	Description
-32000	Server error	Fallback error code when the server is not able to set a more specific code.
-32001	Produce invalid resources	Produce invalid resource(s) in Clarify.
-32002	Found invalid resources	Found invalid resource(s) in Clarify.
-32003	Forbidden	The requested operation is not permitted by your current access token, or that the input parameters are referencing a resource that isn't accessible / doesn't exist.
-32009	Conflict	The operation is not allowed because it causes a conflict with existing resource(s) in Clarify. Could be caused by unique field constraints on resources or concurrent write operations.
-32011	Too many requests	Access to a specific RPC method has been blocked due to rate-limit constraints; reduce the call-rate of the client to stay within the documented rate-limit. Consider sequential instead of concurrent requests.
-32015	Try again	Indicates an availability issue; the client should consider to try the request again after a delay.
-32021	Partial failure	Returned when an operation could only partially be performed.