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" 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 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

RTIG_ERROR

Requests to the Real Time Image Generation (RTIG) endpoint failed to load the Challenge images.

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.

onWarning onError

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

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)

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.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.