Improved Integration Responses

Updated on 26 Feb 2025

Dark

Light
PDF

Article summary

Did you find this summary helpful?

Thank you for your feedback

Whenever an integration makes a call, and that call fails to connect to an external system, the information that's necessary for troubleshooting the failed integration task is now viewable by Itential Platform users, including the:

Method and action (GET, POST, PATCH, etc)
URL (protocol, host, basepath, path)
Response object (status code, body)
Debugging information

This feature enhancement applies to both on-premises and cloud Itential Platform users to ensure they receive the diagnostic information that's needed for troubleshooting when an integration call fails.

Output Error

When an Integration task is not successful in its call to an external system, an output error is returned along with useful information to help troubleshoot the error that is presented.

When the Integration task fails because it does not have the proper information to make the API call, it will output the error as a string, with a message to indicate why it could not make the API call.
When the Integration task fails because the API call was processed by the target server and returned a failure, it will output the error as an object with fields in its response body.

Response Body

Itential has standardized the response body of an Integration task with additional information to help understand why an output error was returned.

Response Field	Description
`ok`	Boolean value stating whether the response was successful.
`method`	HTTP verb that indicates the type of call, e.g., `"method": "GET", "POST", "PUT", "PATCH", "DELETE"`
`url`	The URL of the call that failed, e.g., `"url": "https://server.com/api/v1/some/resource"`
`status`	The HTTP status code returned by the server.
`statusText`	Description of the HTTP status code.
`headers`	An array of response headers of the call.
`body`	The body of the response. Provides information when Itential Platform is able to parse the response. If the error response is not JSON, Itential Platform is not able to parse the response, and the response is then conveyed to a `text` field.
`text`	Generated when Itential Platform cannot parse the body of the response.
`parseError`	Raised when a parsing error has occurred.

ⓘ Note: For some workflows, e.g. clientCredentials, the Itential platform will automatically request new access tokens or use refresh tokens. This may result in an error whereby the Integration task was a "GET" but the error object was induced by a "POST" to "api/v1/token". In this scenario, because the token request failed, the Integration could not even attempt the API call, which is why an error object is returned.

Example: Success Response Body

A Successful sample response body is presented below.

{
  "ok": true,
  "method": "GET",
  "url": "http://localhost:8088/pet/7119",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "connection": "close",
    "content-type": "application/json",
    "date": [
      "Fri",
      "05 May 2023 17:48:43 GMT"
    ],
    "transfer-encoding": "chunked",
    "x-powered-by": "Express"
  },
  "body": {
    "id": 7119,
    "tags": [],
    "status": "available",
    "name": "Lotus",
    "photoUrls": [
      "https://patchpuppy.com/wp-content/uploads/2022/06/WhatIsanAmericanBlackLab.jpg.webp"
    ]
  }
}

Example: Error Response Body

A sample Error response body is presented below.

{
  "ok": false,
  "url": "https://petstore.swagger.io/api/v3/store/invenxxxtory",
  "status": 404,
  "statusText": "Not Found",
  "headers": {
    "access-control-allow-headers": [
      "Content-Type",
      "api_key",
      "Authorization"
    ],
    "access-control-allow-methods": [
      "GET",
      "POST",
      "DELETE",
      "PUT"
    ],
    "access-control-allow-origin": "*",
    "cache-control": "must-revalidate,no-cache,no-store",
    "connection": "keep-alive",
    "content-length": "309",
    "content-type": "text/html; charset=ISO-8859-1",
    "date": [
      "Wed",
      "26 Feb 2025 14:02:35 GMT"
    ],
    "server": "Jetty(9.2.9.v20150224)"
  },
  "text": "<html>\n<head>\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\"/>\n<title>Error 404 Not Found</title>\n</head>\n<body><h2>HTTP ERROR 404</h2>\n<p>Problem accessing /api/v3/store/invenxxxtory. Reason:\n<pre>    Not Found</pre></p><hr><i><small>Powered by Jetty://</small></i><hr/>\n\n</body>\n</html>\n",
  "parseError": {
    "name": "YAMLException",
    "reason": "end of the stream or a document separator is expected",
    "mark": {
      "name": null,
      "buffer": "<html>\n<head>\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\"/>\n<title>Error 404 Not Found</title>\n</head>\n<body><h2>HTTP ERROR 404</h2>\n<p>Problem accessing /api/v3/store/invenxxxtory. Reason:\n<pre>    Not Found</pre></p><hr><i><small>Powered by Jetty://</small></i><hr/>\n\n</body>\n</html>\n",
      "position": 211,
      "line": 6,
      "column": 55,
      "snippet": " 4 |  ... nd</title>\n 5 |  ... \n 6 |  ... </h2>\n 7 |  ... i/v3/store/invenxxxtory. Reason:\n-----------------------------------------^\n 8 |  ... </p><hr><i><small>Powered by Jetty://</small></i><hr/>\n 9 |  ... "
    },
    "message": "end of the stream or a document separator is expected (7:56)\n\n 4 |  ... nd</title>\n 5 |  ... \n 6 |  ... </h2>\n 7 |  ... i/v3/store/invenxxxtory. Reason:\n-----------------------------------------^\n 8 |  ... </p><hr><i><small>Powered by Jetty://</small></i><hr/>\n 9 |  ... "
  },
  "method": "GET"
}

If you are still unable to determine the error reason, please do not hesitate to contact Itential's Product Support Team for additional troubleshooting help.

Was this article helpful?

What's Next

Integration Token Management

Table of contents

Output Error
Response Body