Errors

Every error is the same shape:

{ "error": { "code": "TokenNotFound", "message": "Unknown or revoked secret API key" } }

Branch on code. The message is written for a human reading a log and may change; the code is the contract. A few validation errors from the agent's own endpoints (identification, the pulse, the credential lookup) also carry an issues array naming the fields that failed.

#Codes

The Server API, the assess family and the endpoints the agent and the mobile SDKs call:

The Management API has codes of its own:

404 (EventNotFound, VisitorNotFound; NotFound on the Management API) is returned for a record that does not exist — or that belongs to another environment or organization. That is deliberate: any other answer confirms the record exists.

#Reading a 404

try {
  event = await antibot.getEvent(requestId)
} catch (e) {
  if (e.status === 404) {
    // Either it never existed, or this key cannot see it.
    // Most often: a staging key reading a production request id.
  }
}

If you are getting 404s for events you can see in the dashboard, check which environment your key belongs to.

#Sealed results

unsealEventResponse throws SealedResultError for a payload that is too short, has the wrong header, or cannot be opened by any supplied key — and when it is given no keys at all.

A wrong key and a tampered payload are not distinguished. Both mean do not trust this result, and saying which would tell an attacker whether they had guessed the key. Treat the throw as a denial, not a retry.

#Webhooks

Your endpoint's failures, not ours. Anything outside 2xx, or slower than three seconds, counts as a failure and is retried once after five minutes with the same event id. See Webhooks.

#Signals that are absent rather than false

Not an error, but the same class of mistake:

{ "result": false, "unavailable": true, "reason": "ipPseudonymized" }

unavailable: true means the signal could not be computed. Check it before you read result, or you will treat "no opinion" as "no detection". See Privacy.

#Agent errors

The browser agent throws if apiKey is missing. Network failures reject the promise from get(), and so does any error answer from the API (OriginNotAllowed, TooManyRequests, …), with the status and body in the message.

Identification failing should not take your page down:

let result = null
try {
  result = await agent.get({ ignoreCache: true })
} catch {
  // Decide what an unidentified visitor means for this action.
  // Usually: continue, and let the server treat it as unknown.
}

Whatever you do, do not fail open on the server side because the client did not send a request id. An absent identification is not a clean one.