Handle outages and retries

Choose your outage behaviorCopy Anchor Link

The AbuseZero Node.js SDK's outage option decides what evaluate() returns when AbuseZero can't be reached or returns a retryable error after the SDK's own retries.

import { AbuseZero } from "abusezero/server";

export const abusezero = new AbuseZero({
  key: process.env.ABUSEZERO_SECRET_KEY!,
  outage: "allow",
});

Three cases never become a local decision, whatever you choose:

• Rate limits. A 429 always throws, so request volume can never switch protection off. See Rate limits.
• Bot check errors. Codes starting with BOT_EVIDENCE_ always throw. See Add a bot check.
• Skipped evaluations. These are answers from AbuseZero, covered below and in Skipped evaluations are not errors.

Reuse the idempotency key on every retryCopy Anchor Link

Every write needs an Idempotency-Key of 1 to 128 printable characters with no spaces. Store the key with the claim, and send the same key and the same request body on every retry. A retry then returns the original response instead of repeating the write: no second evaluation, outcome, import or delete.

const idempotencyKey = `evaluate:${claim.claimId}`;
await saveClaimAttempt(claim.claimId, idempotencyKey);
const evaluation = await abusezero.evaluate(input, idempotencyKey);

saveClaimAttempt stands for your own storage. A changed request body needs a new key: the same key with a different body returns IDEMPOTENCY_CONFLICT.

Retry retryable errorsCopy Anchor Link

The Node.js SDK already retries briefly within its own request budget and honors Retry-After. If it still fails, check retryable before you retry.

import { AbuseZeroError } from "abusezero/server";

try {
  return await abusezero.evaluate(input, idempotencyKey);
} catch (error) {
  if (error instanceof AbuseZeroError && error.retryable) {
    await scheduleRetry(claim.claimId, idempotencyKey, error.requestId);
    return { status: "pending" as const };
  }
  throw error;
}

scheduleRetry stands for your own job queue. Retry with the same key.

If you call the REST API directly, apply the same rules: retry 429 and 5xx responses, and responses whose error has "retryable": true, with the same Idempotency-Key, after Retry-After when it is present. Bot check errors are the exception: they need a fresh device token and a new key. Log the X-Request-ID header of every failed response. REST API errors lists every code.

Handle skipped evaluationsCopy Anchor Link

A skipped evaluation means the workspace couldn't run it, so no allow or deny was decided. Your outage setting doesn't apply.

{
  "object": "evaluation",
  "status": "skipped",
  "reason": "insufficient_credits"
}

Handle a skip as its own branch, and treat a reason you don't recognize like any other skip. New reasons can be added within API v1 (REST API versioning). Troubleshooting covers each reason. The workspace owner resolves skips in Workspace settings → Billing & Subscriptions.

if ("status" in evaluation) {
  await alertWorkspaceOwner(evaluation.reason);
  return applyFallback(claim);
}

alertWorkspaceOwner and applyFallback stand for your own alerting and your chosen fallback.

Reconcile local decisionsCopy Anchor Link

When evaluate() returns source: "local_outage", AbuseZero didn't decide the claim. Keep the claim ID and its idempotency key. When AbuseZero is reachable again, evaluate the claim again with the same key and body. If the first request did reach AbuseZero, you get its original result. Otherwise, the claim is evaluated now.

const evaluation = await abusezero.evaluate(input, storedIdempotencyKey);

if (!("status" in evaluation) && evaluation.source === "abusezero" && evaluation.result === "deny") {
  await reviewGrantedDuringOutage(input.claim_id, evaluation);
}

reviewGrantedDuringOutage stands for your own follow-up, such as a review queue.

Verify your integrationCopy Anchor Link

Simulate an outage with a client whose fetch always fails, then check what your code receives.

import { AbuseZero } from "abusezero/server";

const offline = new AbuseZero({
  key: process.env.ABUSEZERO_SECRET_KEY!,
  outage: "allow",
  fetch: async () => { throw new Error("offline"); },
});

const result = await offline.evaluate(input, "outage-check-0001");
console.log(result);

With outage: "allow", result.source is local_outage and result.result is allow. With outage: "throw", the call throws an AbuseZeroError whose retryable is true.