Error handling

  • Published on Dec 19, 2025
Prev Next

Error handling, configured as defaultResponseHandler in the configuration, allows you to define how different error responses from the API are handled and what action the connector should take next.

For example, you can use the default response handler to:

  • Trigger an automatic token refresh attempt when the API responds with the code 401

  • Configure automatic retry of the request when the API responds with the code 429

  • Or show a custom error message to the user based on some other error code

Configuring error handling is optional, but it allows your connector to be more resilient to issues such as expired access tokens or temporary API glitches, and also more user-friendly by providing clear and actionable error messages to the end user.

Example configuration

Below you can see an example configuration that:

  • In case of status code 400 from the API, the user is returned an error message provided in the response field description

  • In case of status code 401 from the API, we attempt to renew the access token automatically and rerun the request. If the renewal fails, we return the message to the user.

  • In case of status code 403 from the API, the user is returned a static error message defined in the message field of the configuration

  • In case of status code 429 from the API, the request is retried automatically according to the retry configuration defined below. If the retries continue to fail, we return the message to the user.

  • Defines a retry strategy with the following rules:

    • maxRetries defines that any request is retried a maximum of 10 times

    • minWait defines a minimum wait of 2 seconds between retries

    • maxWait defines a maximum wait of 60 seconds between retries

    • delayType with value exp defines an exponentially growing delay (in other words, 1, 2, 4, 8, 16, 32, 64… seconds) starting from the minimum wait time and growing up to the maximum wait time.

   "defaultResponseHandler": {
        "responseStatuses": [
            {
                "httpStatus": 400,
                "action": "error",
                "message": "Error",
                "messageDetails": {
                    "source": "jsonPath",
                    "value": "$.description"
                }
            },
            {
                "httpStatus": 401,
                "action": "renew_token",
                "message": "No token or a bad token was provided."
            },
            {
                "httpStatus": 403,
                "action": "error",
                "message": "The server understood the request but refuses to authorize it"
            },
            {
                "httpStatus": 429,
                "action": "retry",
                "message": "Too Many Requests: Rate limiting has been applied."
            }
        ],
        "retry": {
            "maxRetries": 10,
            "minWait": 2,
            "maxWait": 60,
            "delayType": "exp"
        }
    }