Troubleshooting, API Status, and Health Checks
This page tells you:
- How to check on whether the Arkose Labs APIs are up.
- How to see regional health checks.
- How to troubleshoot problems with Arkose Bot Manager.
- How to handle errors you may encounter.
Note the following terminology:
Fail-Open: When we want the overall process to proceed, even when failure conditions for Arkose Bot Manager are present.
Fail-Close: When we want to block the workflow (retry, hard no-go), because failure conditions for Arkose Bot Manager are present.
In general, we recommend that you write your integration with Arkose Bot Manager so that, in the rare event of a disruption of our servers, your system fails-open.
Fail-Open Options: Reducing the Impact of Arkose API Service Disruption
We recommend you integrate and configure Arkose APIs so that they can be bypassed in the rare event of any Arkose API-related service disruption. The following sections discuss options for this and how to troubleshoot customer issues.
Feature Flag
When writing your integration of Arkose Bot Manager with your system:
-
Set up a Feature Flag or key that can turn off Arkose Labs Enforcement on both the Server and Client.
-
If the below issues/symptoms occur, call the Status API as shown later on this page.
-
If the Status response indicates a problem at Arkose Labs, use the Feature Flag to turn off Enforcement.
-
Periodically recheck Arkose’s status.
-
When it returns to being operational, use the Feature Flag to turn Enforcement back on.
Client-Side Troubleshooting
Issue | Symptoms | Mitigation Suggestions |
---|---|---|
The Arkose JS API script does not load. | The onReady callback will NOT be called. | 1. Implement a timer that checks if the onReady callback has been triggered. If not: a. Ask the user to refresh the page b. Retry loading the Arkose API Script 2. Use the Arkose Labs Status API to check for service issues. Based on the response ( none , partial , outage ), take customer specific action as necessary. |
The Arkose API runs, but fails session creation due to not being able to communicate with the Arkose servers. | The onError callback is triggered. | 1. When the onError callback is triggered, call reset to retry creating the session. Then run methods on the Arkose Enforcement Object.2. If onError is triggered multiple times, use the Arkose Labs Status API to check for service issues. Based on the response (none , partial , outage ), take customer specific action as necessary. |
An Enforcement Challenge is shown, but there is a communication error between the EC and the Arkose servers. | The EC shows an error screen, such as:The connection to a verification server was interrupted. To prove you're not a spammer, please refresh this page The EC automatically tries to reconnect with the Arkose servers and continue once it does | 1. Retry session creation by calling the reset() method on the Arkose Enforcement Objecta. In lightbox mode, if the lightbox has been opened, reset() closes the lightbox and resets the challenge. To reopen it, call run() . However, if the error is thrown before the lightbox is triggered to open, just call reset() .2. Use the Arkose Labs Status API to check for service issues. Based on the response ( none , partial , outage ), take customer specific action as necessary. |
Server-Side
Symptoms | Mitigation Suggestions |
---|---|
Unexpectedly long response time from a Verify API call. | 1. Use the Arkose Labs Status API to check for service issues. 2. If there is an outage or disruption, your server should bypass any validity checks for the Arkose token and let the user continue the session. |
Verify API call returns an HTTP error code. | 1. Use the Arkose Labs Status API to check for service issues. 2. If there is an outage or disruption, your server should bypass any validity checks for the Arkose token and let the user continue the session. |
Fail-Open Error Handling Sample Code
<html>
<head>
<meta charset="UTF-8" />
</head>
<body>
<!--
The trigger element can exist anywhere in your page and can be added to the DOM at any time.
-->
<button id="enforcement-trigger">trigger element</button>
<script>
const publicKey = '<YOUR PUBLIC KEY>';
const maxRetryCount = 3;
const arkoseScriptSrc = `https://client-api.arkoselabs.com/v2/<YOUR_PUBLIC_KEY>/api.js`; // Replace <YOUR_PUBLIC_KEY> with the public key that has been setup for your account.
let scriptRetryCount = 0;
let enforcementRetryCount = 0;
function handleFailure() {
// Handle Arkose script failure here
// We strongly advise to confirm the status from the server side
}
function onArkoseScriptError(error) {
if (scriptRetryCount === maxRetryCount) {
removeArkoseScript();
handleFailure();
return;
}
// Retry loading of Arkose script
removeArkoseScript();
createArkoseScript();
scriptRetryCount++;
}
function removeArkoseScript() {
const arkoseScripts = document.querySelectorAll(
`script[src="${arkoseScriptSrc}"]`
);
for (const script of arkoseScripts) {
script.remove();
}
}
function createArkoseScript() {
const script = document.createElement('script');
script.type = 'text/javascript';
script.src = arkoseScriptSrc;
script.setAttribute('data-callback', 'setupEnforcement');
script.async = true;
script.defer = true;
script.onerror = onArkoseScriptError;
script.id = 'arkose-script';
document.head.append(script);
}
async function checkArkoseAPIHealthStatus() {
try {
const healthResponse = await fetch(
'https://status.arkoselabs.com/api/v2/status.json'
);
const healthJson = await healthResponse.json();
const status = healthJson.status.indicator;
return status === 'none'; // status "none" indicates Arkose systems are healthy
} catch (error) {
return false;
}
}
/*
This global function will be invoked when the API is ready. Ensure the name is the same name
that is defined on the attribute `data-callback` in the script tag that loads the api for your
public key.
*/
function setupEnforcement(myEnforcement) {
myEnforcement.setConfig({
selector: '#enforcement-trigger',
onCompleted: function (response) {
console.log(response.token);
},
onError: async function (response) {
const arkoseStatus = await checkArkoseAPIHealthStatus();
if (arkoseStatus && enforcementRetryCount < maxRetryCount) {
myEnforcement.reset();
// To ensure the enforcement has been successfully reset, we need to set a timeout here
setTimeout(function () {
myEnforcement.run();
}, 500);
enforcementRetryCount++;
return;
}
// The Arkose API is unhealthy or retry count has exceeded
handleFailure();
},
});
}
createArkoseScript(); // load Arkose script on page load
</script>
</body>
</html>
Real Time Arkose Labs API Status
You can view real-time status of the Arkose Labs APIs at: http://status.arkoselabs.com.
This takes you to a dashboard that shows the health of Arkose Labs services.
Arkose Labs Status Endpoint
You can check whether the Arkose Labs APIs are up either visually or via an API call,
The Status check API call is:
GET https://status.arkoselabs.com/api/v2/status.json
The call returns one of the following JSON responses. The key part is the status
field and its indicator
and description
subfields which can have these paired values:
Field | Value | Field | Value |
---|---|---|---|
"indicator" | "none" | "description" | "All Systems Operational" |
"indicator" | "minor" | "description" | "Partially Degraded Service" |
"indicator" | "minor" | "description" | "Minor Service Outage" |
"indicator" | "major" | "description" | "Partial System Outage" |
"indicator" | "critical" | "description" | "Major System Outage" |
All Systems Operational
{
"page": {
"id": "ntmkcpjv4jzt",
"name": "Arkose Labs",
"url": "https://status.arkoselabs.com",
"time_zone": "Australia/Brisbane",
"updated_at": "2019-12-21T12:23:44.180+10:00"
},
"status": {
"indicator": "none",
"description": "All Systems Operational"
}
}
Partially Degraded Service (1 or all regions)
{
"page": {
"id": "ntmkcpjv4jzt",
"name": "Arkose Labs",
"url": "https://status.arkoselabs.com",
"time_zone": "Australia/Brisbane",
"updated_at": "2020-03-06T09:01:34.496+10:00"
},
"status": {
"indicator": "minor",
"description": "Partially Degraded Service"
}
}
Partial System Outage (1 or more regions partial outage but not all regions)
{
"page": {
"id": "ntmkcpjv4jzt",
"name": "Arkose Labs",
"url": "https://status.arkoselabs.com",
"time_zone": "Australia/Brisbane",
"updated_at": "2020-03-06T09:07:06.394+10:00"
},
"status": {
"indicator": "minor",
"description": "Minor Service Outage"
}
}
Partial System Outage (All regions)
{
"page": {
"id": "ntmkcpjv4jzt",
"name": "Arkose Labs",
"url": "https://status.arkoselabs.com",
"time_zone": "Australia/Brisbane",
"updated_at": "2020-03-06T09:07:06.394+10:00"
},
"status": {
"indicator": "major",
"description": "Partial System Outage"
}
}
Major System Outage (1 or more regions major outage but not all regions)
{
"page": {
"id": "ntmkcpjv4jzt",
"name": "Arkose Labs",
"url": "https://status.arkoselabs.com",
"time_zone": "Australia/Brisbane",
"updated_at": "2020-03-06T09:07:06.394+10:00"
},
"status": {
"indicator": "major",
"description": "Partial System Outage"
}
}
Major System Outage (All regions major outage)
{
"page": {
"id": "ntmkcpjv4jzt",
"name": "Arkose Labs",
"url": "https://status.arkoselabs.com",
"time_zone": "Australia/Brisbane",
"updated_at": "2020-03-06T09:07:06.394+10:00"
},
"status": {
"indicator": "critical",
"description": "Major System Outage"
}
}
The status:description
will contain information regarding outages. If there are no outages it will contain All Systems Operational.
Using the API Status Endpoint With Your Service
We use the term Fail Open to mean that even when failure conditions for the Arkose Platform are present, we want the overall process to proceed. We recommend you integrate and configure Arkose APIs so that they can be bypassed in the rare event of any Arkose API-related service disruption and your process can proceed.
Server-Side
On the server side, Verify API calls ensure that a valid token is present. An unexpectedly long response time or server side HTTP error code could signal an issue with a call. To rule out localized issues, please check Arkose Services' status by calling the Arkose Status API as shown above. You can use the response (All Systems Operational
, Partially Degraded Service
, Minor Service Outage
, Partial System Outage
, or Major System Outage
) to decide on the right fallback flow. If there is an outage or disruption, then your server should bypass any validity checks for the Arkose token and let the user continue the session.
Client-Side
An unexpected failure of the Client API could stop a website from loading or negatively impact the user experience. Use the Arkose Client API's onError()
callback to handle errors gracefully.
When the Client API request timeouts, use the Enforcement Object's reset
callback to retry the call. If the issue persists, check the service's status by calling the Arkose Status API as shown above. If the response confirms an outage, switch to your system's fallback flow. You should check for other JavaScript or third-party errors before bypassing the Arkose Client API or switching to a fallback option.
Regional Endpoint Health Checks
The values in the table below are subject to change at any time.
Use the following code to access regional health checks and response time information:
// General format:
GET https://status.arkoselabs.com/metrics-display/{component_ID}/{timerange}
// Or for a specific example getting the Singapore response time:
GET https://status.arkoselabs.com/metrics-display/13lww8jwjcfq/day.json
Use the table below to get the correct component_ID
and timerange
.
Healthcheck | component_id | timerange |
---|---|---|
North Virginia Healthcheck | x7vj2bf6ckzv | day.json week.json month.json |
North Virginia Response Time | 6wbnmjn5w03x | day.json week.json month.json |
Oregon Healthcheck | f5txw3k5rpbs | day.json week.json month.json |
Oregon Response Time | m3pl0rjry4cy | day.json week.json month.json |
Singapore Healthcheck | p3frx5vqjd5x | day.json week.json month.json |
Singapore Response Time | 13lww8jwjcfq | day.json week.json month.json |
Ireland Healthcheck | cdplvgx9msf1 | day.json week.json month.json |
Ireland Response Time | 8t7xx4yjbswj | day.json week.json month.json |
Sydney Healthcheck | wcd34f7xkc0c | day.json week.json month.json |
Sydney Response Time | gljgfg9zqpcg | day.json week.json month.json |
Here is a sample of code interrogates the Regional Endpoints for status and metrics.
const axios = require("axios");
const NorthVirginiaHealth = "x7vj2bf6ckzv";
const NorthVirginiaTiming = "6wbnmjn5w03x";
function getOperationalStatus() {
axios
.get(`https://status.arkoselabs.com/api/v2/status.json`)
.then(function(response) {
console.log(`Arkose Labs Status: ${response.data.status.description}`);
})
.catch(function(error) {
console.log(error);
});
}
function getCurrentHealthcheck(endpoint, timerange) {
axios
.get(
`https://status.arkoselabs.com/metrics-display/${endpoint}/${timerange}`
)
.then(function(response) {
console.log(`North Virginia health is ${response.data.summary.last}%`);
})
.catch(function(error) {
console.log(error);
});
}
function getLastResponseTiming(endpoint, timerange) {
axios
.get(
`https://status.arkoselabs.com/metrics-display/${endpoint}/${timerange}`
)
.then(function(response) {
console.log(`North Virginia last response time was: ${response.data.summary.last}ms`);
})
.catch(function(error) {
console.log(error);
});
}
Updated 6 days ago