Client-Side Error Handling

onError Callback

In version 8.11.0 of our Client-API we introduced an onError callback that a customer can use to listen for occurrences of errors in our platform and allow the customer to take action when they occur.

The callback is similar to other Client-API callbacks and can be implemented in the following way:

<html>
<head>
  <script src="//client-api.arkoselabs.com/v2/<YOUR PUBLIC KEY>/api.js" data-callback="setupEnforcement" async defer></script>
  <meta charset="UTF-8">
</head>
<body>
<button id="enforcement-trigger">
  trigger element
</button>
<script>
  function setupEnforcement(myEnforcement) {
    myEnforcement.setConfig({
      selector: '#enforcement-trigger',
      onCompleted: function(response) {
        console.log(response.token);
      },
      onError: function(response) {
        // in onError the response object will have an `error` object as a property
        const arkoseError = response.error;
        // the error object will have an additional property of `error` which will be an
        // error code indicating where the error occured
        console.log(arkoseError.error)
      }
    });
  }
</script>
</body>
</html>

The response object that is returned from onError includes an error object that then has a property of error which is an error code that can help indicate where in the Arkose Enforcement Challenges the error is being thrown.

An example for the response object that is passed to onError is as follows:

{
  error: {
    error: 'CHALLENGE_ERROR'
  }
}

Error Codes

The following table includes information for the different error code values that could be passed to the onError callback.

Error CodeDescription
SRI_ERRORapi.js script was downloaded but it did not match the hash provided.
(Only applicable to hosted iframes with Sub-Resource Integrity enabled keys)
CHALLENGE_ERRORArkose Client-API javascript fails to load.
API_REQUEST_TIMEOUTArkose setup session call timeout, our timeout is currently set to 20 seconds.
API_REQUEST_ERRORArkose setup session call threw an error.
FC_SCRIPT_ERROR
Note: this will be available from 8th Dec AEST with ec-api_v5.30.0 release		Arkose Enforcement Challenge script/s fail to load.

FC_SCRIPT_ERROR also includes an additional property source alongside the error code. This property contains the URL of the script that failed to load. For example:

{ error: 'FC_SCRIPT_ERROR', source: '<https://client-api.arkoselabs.com/cdn/fc/[hash]/standard/fc_bootstrap.js>' }

Script onerror

We also suggest hooking into the native onerror callback when loading the initial Arkose Labs Client-API entrypoint file api.js.

By also listening to this onerror callback a customer is able to catch any error that may occur during the loading of that initial api.js javascript file.

An example on how to do this is as follows:

<html>
<head>
  <meta charset="UTF-8">
</head>
<body>
<button id="enforcement-trigger">
  trigger element
</button>
<script>
  function createArkoseScript() {
    const script = document.createElement('script');
    script.type = 'text/javascript';
    script.src = '//client-api.arkoselabs.com/v2/<YOUR PUBLIC KEY>/api.js'
    script.setAttribute('data-callback', 'setupEnforcement');
    script.async = true;
    script.defer = true;
    script.onerror = function () {
      // handle loading error here
    };
    document.head.append(script);
  }

  function setupEnforcement(myEnforcement) {
    myEnforcement.setConfig({
      selector: '#enforcement-trigger',
      onCompleted: function(response) {
        console.log(response.token);
      },
      onError: function(response) {
        // in onError the response object will have an `error` object as a property
        const arkoseError = response.error;
        // the error object will have an additional property of `error` which will be an
        // error string indicating where the error occured
        console.log(arkoseError.error)
      }
    });
  }

  createArkoseScript();
</script>
</body>
</html>

For more details around the Arkose Client-API please view our developer documentation here: Client API , and for more details around checking the status of Arkose APIs and handling errors please view the following documentation: Troubleshooting, API Status, and Health Checks.

Updated over 1 year ago