Client-Side Error Handling

onError Callback

Our Client-API has an onError callback that customers can use to listen for errors in our platform and 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="//<company>-api.arkoselabs.com/v2/<YOUR PUBLIC KEY>/api.js" data-callback="setupEnforcement" ></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, onWarning and onFailed 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, onWarning and onFailed callbacks.

Error Code	Description	Callback
`API_REQUEST_TIMEOUT`	Arkose setup session call timeout, our timeout is currently set to 20 seconds.	onError
`API_REQUEST_ERROR`	Arkose setup session call threw an error.	onError
`CHALLENGE_ERROR`	Arkose Client-API javascript fails to load.	onError
`FC_SCRIPT_ERROR`	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' }`	onError
`SRI_ERROR`	`api.js` script was downloaded but it did not match the hash provided. (Only applicable to hosted iframes with Sub-Resource Integrity enabled keys)	onError
`POW_ERROR`	When PoW fails to submit an answer, the error handling depends on the operational mode. In transparent mode, the `onError` callback is invoked, while in interactive mode, the `onWarning` callback is used.	onError onWarning
`POW_FAILED`	When PoW results in an action of block. Terminating use case.	onFailed
`GAME_LIMIT_CUSTOM`	When a custom game limit is reached. Terminating use case.	onFailed
`GAME_LIMIT_DEFAULT`	When a default game limit is reached. Users are presented with option to load a new game.	onFailed
`RTIG_ERROR`	Requests to the Real Time Image Generation (RTIG) endpoint failed to load the Challenge images.	onWarning
`CDN_ASSET_ERROR`	Request to fetch example correct/incorrect images on fail screen failed.	onWarning
`CHECK_ANSWER_ERROR`	Request to submit an answer for a challenge failed.	onWarning
`DAPIB_ERROR`	Unable to load DAPIB script, or unable to successfully transform answer.	onWarning
`DAPIB_SRI_ERROR`	Request to fetch DAPIB script’s SRI hash failed.	onWarning
`GAME_SETUP_ERROR`	Request to create a new game/challenge failed.	onWarning
`GET_EKEY_ERROR`	Request to fetch an encryption key failed.	onWarning
`RTAG_ERROR`	Request to the Real Time Audio Generation (RTAG) endpoint failed to load the Challenge audio file.	onWarning

Script `onerror`

We also suggest hooking into the native onerror callback when loading the initial Arkose Labs Client-API entry point 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.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.

onError Callback

Error Codes

Script onerror

Script `onerror`