Error handling (3rd party)

Overview

When calling operations using the Call connector endpoint, even though your payload may have passed Tray's input schema validation, you may encounter errors returned by the 3rd party.

Therefore a 200 response does not necessarily indicate success from 3rd party.

A 200 response will contain an outcome and a output field.

If outcome is success, that means 3rd party service gave a successful response.

If outcome is error, that means 3rd party service gave an error response.

In either case, the response from the 3rd party can be obtained from output field.

Error examples

For example the following call to Trello to get a board with a board_id that does not exist will return a status of 200 from Tray, as the input met Tray's schema requirements, but within the 200 response we will see that Trello has returned a 404:

{
  "operation": "get_board_by_id",
  "authId": "fc2axxxx-xxxx-xxxx-xxxx-xxxxf80c51de",
  "input": {
    "include_cards": "none",
    "include_lists": "all",
    "include_members": "all",
    "include_labels": "all",
    "fields": "all",
    "board_id": "Qd1ov5o0"
  },
  "returnOutputSchema": false
}

{
  "outcome": "error",
  "output": {
    "response": {
      "statusCode": 404,
      "body": "Board not found"
    },
    "expects": {
      "statusCode": [200, 201, 202, 203, 204]
    },
    "message": "Not found. Looks like this has been removed."
  }
}

Likewise the following call to Google Sheets which attempts to get the rows for a non-existent spreadsheet ID:

{
  "operation": "get_rows",
  "authId": "925axxxx-xxxx-xxxx-xxxx-xxxxfc72acdc",
  "input": {
    "number_of_rows": 100,
    "spreadsheet_id": "13TF-oSS0OhxxxxxxxxxxxxxbMmgVIhfZ2a49",
    "worksheet_name": "Sheet1"
  },
  "returnOutputSchema": false
}

{
  "outcome": "error",
  "output": {
    "response": {
      "statusCode": 404,
      "body": {
        "error": {
          "code": 404,
          "message": "Requested entity was not found.",
          "status": "NOT_FOUND"
        }
      }
    },
    "expects": {
      "statusCode": [200]
    },
    "message": "Not found. Looks like this has been removed."
  }
}

Note that the exact error resonse format will vary from service to service, so some manual testing will be required to establish what this format is.

Refer the secton below on how to do this.

Investigation of services

It is highly recommended that you make use of our Form Builder demo app to test out the connector operations you will be making use of in your integration.

This app allows you to:

• Send live calls to the 3rd party in question
• Inspect the input payload as it is constructed
• Inspect the success or failure responses from the 3rd party
• Edit the input payload in order to force and inspect errors

This will enable you to get a full grasp of how the 3rd party returns errors (3rd party error handling is not yet fully standardized by Tray's API).

It will also allow you to explore any unexpected responses and idiosyncracies you may encounter with 3rd parties.

Investigation example

If we want to investigate the Google Sheets get_rows operation, we can set up the form as follows:

We can then use the rendered form to enter values in the relevant boxes:

And inspect the input payload as it is being built, along with a successful output from Google:

If we are working with the following sheet:

We can see that Google has set the column_heading to be A rather than User

We may wish to test what happens if we edit the input payload to "column_heading": "User" to see if it will still work.

The answer is no!

But as you can see, Google has not returned an error. Instead it has returned an empty result:

If you follow best practices in terms of programmatically working with our schema, as outlined in our Building a UI form tutorial you should be able to avoid errors with these idiosyncracies.

However it is highly recommended you investigate connector operations thoroughly so you know exactly what you are dealing with.