Documentation

Everything you need to put WAU Captcha in front of a form or an API.

Examples use this installation's address, https://api.waucaptcha.com. Replace it with yours if you run your own.

How it works

A captcha check takes three calls. Your page fetches a challenge with the public site key, the person answers it and gets a one-time token, and your server redeems the token with the secret key before accepting the request.

Diagram of a verification in 12 steps. Your site's frontend fetches a challenge from wau-challenge with the site key, sends the answer to wau-verify, which has wau-challenge check it, and gets a one-time token. Your backend redeems the token at /siteverify with the secret key and gets success, the challenge type and the hostname. Challenges and grants live in a Redis Cluster and each works once.
The numbers follow the calls in order; wau-challenge and wau-verify sit behind api.waucaptcha.com. Open at full size

Your keys

  • Site key (pk_…) — public. Used in the browser to fetch challenges.
  • Secret key (sk_…) — private. Used by your server to redeem tokens. Never ship it to a browser.
  • Create a key pair on the API keys page of the dashboard.

Quick start

  1. Create an API key in the dashboard and copy its site key and secret key.
  2. Add the widget, or <WauCaptcha /> in React, to your form. Once solved, the form sends a hidden field named wau-captcha-token.
  3. On your server, redeem that token with the secret key and reject the request when it fails.

Browser widget

The widget shows the challenge, a text box and two buttons (for slide_puzzle, a slider instead of the text box and Verify; for animal_jump, the two rounds and a Replay button; for object_rotate, the two rounds with Rotate left, Rotate right and Done, which the arrow keys and Enter work too; for auto_check, a compact box that checks the visitor in the background, with a challenge of its fallback type in its place only when the check is unsure), and loads a new challenge after a wrong answer. With the script build, any element with data-wau-captcha renders by itself.

html
<script  src="https://cdn.jsdelivr.net/npm/@waucaptcha-sdk/client@1.7.0/dist/wau-captcha.global.js"  integrity="sha384-6HEd83rCb1Wox8RT7prjB5GeuWB7ylmSj1DBZ9+2varqFoa+2OMJKpCYl7xktRTs"  crossorigin="anonymous"></script><form action="/signup" method="post">  <input name="email" type="email" required />  <div data-wau-captcha data-site-key="pk_…" data-base-url="https://api.waucaptcha.com"></div>  <button type="submit">Sign up</button></form>

The snippet loads an exact release, 1.7.0, with its integrity hash: the browser refuses the file if it differs by a byte from the one published, so neither the CDN nor a later release can change what runs on your page. To move to another release, change the version in the URL and compute its hash:

bash
# In a clone of github.com/wau-captcha/wau-sdk-js:node scripts/sri.mjs 1.7.0# Or with curl and openssl:curl -s https://cdn.jsdelivr.net/npm/@waucaptcha-sdk/client@1.7.0/dist/wau-captcha.global.js \  | openssl dgst -sha384 -binary | openssl base64 -A

Attributes: data-site-key and data-base-url (required), data-challenge-type (image_distort, motion_noise, slide_puzzle, animal_jump, object_rotate or auto_check), for auto_check data-fallback-type (slide_puzzle by default) and data-appearance (always or interaction-only), data-input-name (default wau-captcha-token) and data-lang (vi for Vietnamese texts).

With a bundler, render it yourself to get callbacks and your own labels:

bash
npm install @waucaptcha-sdk/client
javascript
import { renderWidget } from "@waucaptcha-sdk/client";const widget = renderWidget(document.querySelector("#captcha"), {  siteKey: "pk_…",  baseUrl: "https://api.waucaptcha.com",  onSuccess(token) {    // Also in the hidden input "wau-captcha-token" of the surrounding form.  },  onError(error) {    console.error(error.code, error.message);  },});

React component

@waucaptcha-sdk/react gives you one component, <WauCaptcha />, for React 18 or later. Put it inside a form: once solved, the form sends the token in the hidden field wau-captcha-token.

bash
npm install @waucaptcha-sdk/react

Next.js App Router

It works straight from a Server Component page; the server action of the form redeems the token with @waucaptcha-sdk/server.

app/signup/page.tsx
import { WauCaptcha } from "@waucaptcha-sdk/react";import { signUp } from "./actions";export default function SignUpPage() {  return (    <form action={signUp}>      <input name="email" type="email" required />      <WauCaptcha siteKey="pk_…" baseUrl="https://api.waucaptcha.com" />      <button type="submit">Sign up</button>    </form>  );}
app/signup/actions.ts
"use server";import { BehaviorVerdict, WauCaptchaServer, hostnameMatches } from "@waucaptcha-sdk/server";export async function signUp(formData: FormData) {  const captcha = new WauCaptchaServer({    secretKey: process.env.WAU_SECRET_KEY!,    baseUrl: "https://api.waucaptcha.com",  });  const result = await captcha.verifyToken(String(formData.get("wau-captcha-token") ?? ""));  // hostname is the website the captcha was solved on: it must be one of yours, listed in  // WAU_ALLOWED_HOSTNAMES, e.g. shop.example.com,https://www.shop.example.com  if (!result.success || !hostnameMatches(result.hostname, process.env.WAU_ALLOWED_HOSTNAMES)) {    throw new Error("Please solve the captcha.");  }  // Sign-up accepts human only: suspicious is a scripted session, and not_measured means the  // client sent no behaviour data (an SDK before 1.2.0 or a hand-written call), so it is untrusted.  if (result.behavior.verdict !== BehaviorVerdict.HUMAN) throw new Error("Please try again.");  // … create the account}

Modal mode

WauCaptchaMode.MODAL shows a box like auto_check's: a checkbox with “I'm not a robot” that opens the challenge in a dialog, which closes by itself once the answer is right; the box then shows a check mark and “Verified”. The challenge only loads when the dialog opens. It needs @waucaptcha-sdk/react 1.7.0 or later; before, it was a button. Callbacks such as onSuccess need a Client Component.

app/signup/signup-captcha.tsx
"use client";import { ChallengeType, WauCaptcha, WauCaptchaMode } from "@waucaptcha-sdk/react";export function SignUpCaptcha() {  return (    <WauCaptcha      mode={WauCaptchaMode.MODAL}      challengeType={ChallengeType.MOTION_NOISE}      siteKey="pk_…"      baseUrl="https://api.waucaptcha.com"      onSuccess={(token) => console.log("solved", token)}      onError={(error) => console.error(error.code)}    />  );}

Props

PropDescription
siteKey, baseUrlRequired: the site key of your API key and the address of the WAU Captcha API.
modeWauCaptchaMode.INLINE (default) shows the challenge in place; WauCaptchaMode.MODAL opens it in a dialog from a checkbox. ChallengeType.AUTO_CHECK always runs in place.
challengeTypeChallengeType.IMAGE_DISTORT (default), ChallengeType.MOTION_NOISE, ChallengeType.SLIDE_PUZZLE, ChallengeType.ANIMAL_JUMP, ChallengeType.OBJECT_ROTATE or ChallengeType.AUTO_CHECK.
fallbackChallengeTypeAUTO_CHECK only: the type shown to a visitor the check is unsure of. ChallengeType.SLIDE_PUZZLE by default; IMAGE_DISTORT where people use a keyboard alone.
appearanceAUTO_CHECK only: Appearance.ALWAYS (default) shows the box from the start; Appearance.INTERACTION_ONLY keeps the captcha hidden unless the fallback or an error must be shown.
themeWauCaptchaTheme.AUTO (default) follows the color-scheme of the page; LIGHT and DARK force one.
inputNameName of the hidden field that carries the token. Default wau-captcha-token.
labelsTexts to replace in your language, e.g. { notRobot: "I'm not a robot", open: "Verify you are human", verify: "Verify" }.
onSuccess, onExpire, onErrorCalled with the token of a right answer, when the token expires unused, and with a WauCaptchaError.

To start over, e.g. after the backend has redeemed the token, change the component's key. To match your brand, set --wau-captcha-primary, --wau-captcha-background or --wau-captcha-border on it or on an ancestor.

Custom UI in the browser

Use WauCaptchaClient to build your own interface. Fetch a challenge when it is shown, not ahead of time: from 1.3.0 the client solves its proof of work in the background meanwhile, and sends it and the site key with the answer. Pass what recordBehavior recorded as behavior, or keys that require behaviour data refuse the answer. For slide_puzzle, animal_jump and object_rotate, trackSlide, trackJump and trackRotate record the drag, the clicks and the presses the way the service checks them, and verifySlide, verifyJump and verifyRotate send them. For auto_check, fetch with newChallenge({ challengeType: ChallengeType.AUTO_CHECK, fallbackType }), record with recordBehavior({ root, page: true }), run probeBrowser(), and once workDone(challenge.id) has resolved and at least 1.5 s have passed since the challenge arrived, send the probe with verifyAuto; success false means a challenge of challenge.fallbackType must be solved instead. A challenge can be answered once: after a wrong answer, fetch a new one.

javascript
import { ChallengeType, WauCaptchaClient } from "@waucaptcha-sdk/client";const captcha = new WauCaptchaClient({ siteKey: "pk_…", baseUrl: "https://api.waucaptcha.com" });// Fetch it when it is shown, not ahead of time. The client solves its proof of work meanwhile.const challenge = await captcha.newChallenge(); // or { challengeType: ChallengeType.MOTION_NOISE }image.src = challenge.imageUrl;image.width = challenge.width;image.height = challenge.height;// Sends the site key and the proof of work too; pass { behavior } from recordBehavior as well.const result = await captcha.verify(challenge.id, input.value);if (result.success) {  // Send result.token to your server with the form.} else {  // Wrong answer: the challenge is used up, fetch a new one.}

Verify on a Node.js server

Redeem the token with @waucaptcha-sdk/server (Node.js 18 or later), and check result.hostname, the website the challenge was solved on, against your own domains with hostnameMatches, which also reads them written with https:// or a port. A thrown WauCaptchaError means the token could not be checked; treat it as a failure.

bash
npm install @waucaptcha-sdk/server
javascript
import { BehaviorVerdict, ErrorCode, WauCaptchaServer, hostnameMatches } from "@waucaptcha-sdk/server";const wau = new WauCaptchaServer({  secretKey: process.env.WAU_SECRET_KEY,  baseUrl: "https://api.waucaptcha.com",});app.post("/signup", async (req, res) => {  try {    const result = await wau.verifyToken(req.body["wau-captcha-token"]);    // hostname is the website the captcha was solved on: it must be one of yours, listed in    // WAU_ALLOWED_HOSTNAMES, e.g. shop.example.com,https://www.shop.example.com    if (!result.success || !hostnameMatches(result.hostname, process.env.WAU_ALLOWED_HOSTNAMES)) {      return res.status(400).send("Please solve the captcha.");    }    // result.behavior: { verdict, score, reasons }. not_measured means no behaviour data was sent:    // untrusted. Decide about suspicious per form; for sign-up, accept human only.    if (result.behavior.verdict !== BehaviorVerdict.HUMAN) return res.status(400).send("Please try again.");  } catch (error) {    if (error.code === ErrorCode.SECRET_KEY_INVALID) console.error("Check WAU_SECRET_KEY");    return res.status(503).send("Captcha check unavailable."); // fail closed  }  // … create the account});

Verify the package

From 1.3.0 on, every release of the three packages is built and published by GitHub Actions with npm provenance: the package page on npmjs.com shows the commit and the workflow it came from. npm audit signatures checks the registry signatures and provenance attestations of what you installed. Releases before 1.3.0 were published by hand and carry no provenance.

bash
npm install @waucaptcha-sdk/servernpm audit signatures

Verify on a Java server

Redeem the token with com.waucaptcha:waucaptcha-sdk (Java 17 or later, no dependencies), and check result.hostname(), the website the challenge was solved on, against your own domains with result.hostnameMatches, which also reads them written with https:// or a port. result.challengeType() is auto_check for a visitor who passed without a puzzle. The client is immutable and safe to share between threads; a WauCaptchaException means the token could not be checked, so treat it as a failure.

xml
<dependency>    <groupId>com.waucaptcha</groupId>    <artifactId>waucaptcha-sdk</artifactId>    <version>1.1.0</version></dependency>
kotlin
implementation("com.waucaptcha:waucaptcha-sdk:1.1.0")
java
import com.waucaptcha.BehaviorVerdict;import com.waucaptcha.ErrorCode;import com.waucaptcha.SiteVerifyResult;import com.waucaptcha.WauCaptchaClient;import com.waucaptcha.WauCaptchaException;// Build it once and share it: it is immutable and safe to use from many threads.WauCaptchaClient wau = WauCaptchaClient.builder()        .baseUrl("https://api.waucaptcha.com")        .secretKey(System.getenv("WAU_SECRET_KEY"))        .build();boolean captchaPassed(String token) {    try {        SiteVerifyResult result = wau.verifyToken(token);        // hostname is the website the captcha was solved on: it must be one of yours, listed in        // WAU_ALLOWED_HOSTNAMES, e.g. shop.example.com,https://www.shop.example.com        if (!result.hostnameMatches(System.getenv("WAU_ALLOWED_HOSTNAMES"))) return false;        // result.behavior(): verdict, score, reasons. NOT_MEASURED means no behaviour data was sent:        // untrusted. Decide about SUSPICIOUS per form; for sign-up, accept HUMAN only.        return result.behavior().verdict() == BehaviorVerdict.HUMAN;    } catch (WauCaptchaException e) {        if (ErrorCode.SECRET_KEY_INVALID.equals(e.getCode())) log.error("Check WAU_SECRET_KEY");        return false; // fail closed: the token could not be checked    }}

The same client fetches and answers challenges of every type but auto_check, whose answer only the browser SDK can give, with the site key, and sends the site key and the proof of work as the browser SDK does. Keys that require behaviour data, the default for new keys, refuse answers sent without a Behavior, so these calls suit tests and desktop apps; on a website, use the JavaScript widget and verify its token in Java.

java
WauCaptchaClient captcha = WauCaptchaClient.builder()        .baseUrl("https://api.waucaptcha.com")        .siteKey("pk_…")        .build();Challenge challenge = captcha.newChallenge(ChallengeType.OBJECT_ROTATE);// Show frame 0 of challenge.image(), then of challenge.secondImage(): each is a strip of// challenge.frameCount() frames. Record each round's presses, as RotateRound(frame, presses,// doneMs), and how the person behaved. The call sends the site key and the proof of work too.AnswerResult result = captcha.verifyRotate(challenge, List.of(round1, round2), behavior);if (result.success()) {    // Send result.token() to your server, which redeems it with verifyToken.}

Other languages

There is no SDK for other languages yet, and none is needed: any backend redeems a token with one HTTPS call to /siteverify, the secret key as a bearer token and the token in a JSON body. Treat anything but a 200 reply with success true as a failed check.

bash
curl -X POST "https://api.waucaptcha.com/siteverify" \  -H "Authorization: Bearer $WAU_SECRET_KEY" \  -H "Content-Type: application/json" \  -d "{\"token\": \"$TOKEN\"}"{  "success": true,  "challenge_type": "image_distort",  "challenge_ts": "2026-09-23T08:15:02Z",  "behavior": { "verdict": "human", "score": 1, "reasons": [] },  "hostname": "shop.example.com"}

Bind a key to your websites

Add your domains on the key's page. Challenges are then issued only to pages on those websites, an answer must come from the website that fetched its challenge and name the same site key, and /siteverify returns the website as hostname.

On your server, check hostname against your own domains and refuse the token when it is none of them. hostnameMatches (@waucaptcha-sdk/server 1.7.0 or later) and result.hostnameMatches (Java) do it: they take the domains as a list or as one string with commas between them, such as an environment variable, and read https://Shop.example.com/, shop.example.com:443 and shop.example.com as the same; *.example.com stands for the subdomains of example.com:

javascript
import { hostnameMatches } from "@waucaptcha-sdk/server";// WAU_ALLOWED_HOSTNAMES=shop.example.com,https://www.shop.example.com,*.shop.example.comconst result = await wau.verifyToken(token);if (!result.success || !hostnameMatches(result.hostname, process.env.WAU_ALLOWED_HOSTNAMES)) {  // Unknown token, or solved on another website: refuse the request.}

The browser sets Origin, so domain binding stops other websites from using your key in their visitors' browsers. A script outside a browser can send any Origin it likes: bots are caught by the behaviour verdict and the service's own signals, not by the domain list.

What each SDK version sends

Every request older SDKs send still works; what changes is how much the service can check.

Versionsite_keyBehaviour dataProof of workBrowser hintsToken to /siteverify
client 1.3.0+, react 1.2.0+, server 1.3.0+YesYesYesYesJSON body
Java 1.0.0+YesNoYesNoJSON body
client 1.2.0, server 1.2.0NoYesNoNoQuery string (deprecated)
client and server 1.1.xNoNoNoNoQuery string (deprecated)

An older client keeps working: without a proof of work its verdict is at most suspicious, and one that sends no behaviour data gets not_measured. It is refused only by a key that requires behaviour data, as new keys do: update to 1.3.0, or turn that switch off on the key's page while you do. The Java SDK records no behaviour itself: it sends a Behavior only when you pass one, so its challenge calls suit tests and desktop apps.

REST API

The SDKs call these endpoints; any HTTP client can call them too. Errors come back as JSON {code, reason, message, metadata}.

GET /challenge/new

Issues a challenge. Query: site_key (required), challenge_type (image_distort by default). image is base64; display it at width × height CSS pixels. slide_puzzle adds piece_image, piece_y, piece_width and piece_height; animal_jump adds second_image, round 2, while image is round 1; object_rotate adds second_image too, and frame_count: image and second_image are each a strip of frame_count frames of width × height side by side. For auto_check, the query takes fallback_type, the type the site prefers if the check does not pass; the reply has no image (image and mime_type empty, width and height 0) and adds fallback_type, the type to load if it does not pass, which the service chooses from what the key allows (empty when it allows none). pow_salt and pow_difficulty are the proof of work the SDK solves before it answers; auto_check asks for more of it. For a key with allowed domains, the Origin of the request (or else of its Referer) must be one of them: DOMAIN_NOT_ALLOWED otherwise.

bash
curl "https://api.waucaptcha.com/challenge/new?site_key=pk_…&challenge_type=image_distort"{  "challenge_id": "0f9c…",  "challenge_type": "image_distort",  "image": "iVBORw0KGgo…",  "mime_type": "image/png",  "width": 200,  "height": 70,  "expires_in": 120,  "pow_salt": "q2Jq0tbV1Wm9u3hS5bH0pA==",  "pow_difficulty": 15}

POST /challenge/verify

Checks an answer. success is false after a wrong answer; the challenge is used up either way. The SDKs also send site_key, pow_nonce (the proof of work) and behavior, how the person behaved while the challenge was on screen. An answer to a challenge of another key, or from another website than the one that fetched it, is wrong. A key that requires behaviour data answers 400 BEHAVIOR_REQUIRED to an answer without it. For auto_check, answer is the JSON the SDK writes from its browser checks, {"v": 1, "ua": …, "lang": …, "f": […]}, from SDK 1.7.0 with "c", the clearance the browser keeps, and "m", counts of how its mouse moves were made, both optional; success false means: show a challenge of its fallback_type. The reply never says why. After a right answer to any other type the reply also carries clearance, which the browser SDK keeps for auto_check; your backend never needs it.

bash
curl -X POST "https://api.waucaptcha.com/challenge/verify" \  -H "Content-Type: application/json" \  -d '{"challenge_id": "0f9c…", "answer": "a8Kq2", "site_key": "pk_…", "pow_nonce": "48213", "behavior": { "version": 1, "elapsed_ms": 4210, … }}'{ "success": true, "token": "…", "expires_in": 120, "clearance": "…" }

POST /siteverify

Redeems a token, once. Send the secret key as a bearer token and the token in the body, as JSON {"token": "…"} or as the form token=…, so it never lands in access logs; the query form (?token=) still works for SDKs before 1.3.0 but is deprecated. success is false when the token is unknown, expired, already used or issued for another key. behavior is the verdict of the behaviour check: human, suspicious or not_measured, a score from 0 to 1 and the reasons. hostname is the website the challenge was solved on. challenge_type is auto_check for a visitor who passed without a puzzle, with the reason cleared or first_visit in behavior.reasons, and the fallback's type for one who solved the fallback.

bash
curl -X POST "https://api.waucaptcha.com/siteverify" \  -H "Authorization: Bearer $WAU_SECRET_KEY" \  -H "Content-Type: application/json" \  -d "{\"token\": \"$TOKEN\"}"{  "success": true,  "challenge_type": "image_distort",  "challenge_ts": "2026-09-23T08:15:02Z",  "behavior": { "verdict": "human", "score": 1, "reasons": [] },  "hostname": "shop.example.com"}

Challenge types

  • image_distort — five characters (letters and digits) distorted in a PNG. The default.
  • motion_noise — five characters (capital letters and digits, without O, 0, Q, I and 1) hidden in a looping animated GIF of moving dots.
  • slide_puzzle — a 300 × 150 JPEG background with a hole, and a PNG piece to drag horizontally into it. The answer is JSON the SDK writes from the drag, which is also checked for human movement, so use the SDK rather than building it by hand. Keyboard-only users cannot solve it: keep image_distort available where accessibility matters.
  • animal_jump — two animated GIFs of 300 × 150, one per round, each playing once for 2 s: five animal heads jump, and one makes a jump clearly higher than every other. The answer is JSON the SDK writes from the click on each round, {"c": [{"x": …, "y": …, "ms": …, "p": …}, …]}: both clicks must land on the highest jumper, after its jump was on screen. The widget plays each round from a blob: URL, so a Content-Security-Policy must allow blob: in img-src. Keyboard-only users cannot solve it: keep image_distort available where accessibility matters.
  • object_rotate — two JPEG strips, one per round, each 8 frames of 300 × 150 side by side. Every frame has two panels seen from the same camera, an arrow on the ground on the left and the object on the right, so the arrow never covers the object; frame k is the object turned k steps clockwise as seen from above. The person turns it a frame at a time, from frame 0, until it faces the way the arrow points, and presses Done. The answer is JSON the SDK writes from the presses, {"r": [{"f": …, "s": [[ms, d], …], "done": …}, …]}: in each round the presses must lead to the frame that faces the arrow, at a person's pace. It works with the keyboard as well as a pointer, but needs sight.
  • auto_check — no image: a compact box of about 300 × 64 checks the visitor in the background while the browser solves a proof of work of 18 bits instead of 15. The answer is JSON the SDK writes from its browser checks, and the behaviour is recorded on the whole page. Most visitors pass with no action and get a token; the rest get a challenge of fallback_type in the same place. An automatic pass needs a clearance from a puzzle solved before or, in balanced mode, is a first visit, at most 5 an hour per address; an address of a cloud or hosting provider never passes automatically, and one address gets at most 30 automatic passes an hour. It is as accessible as its fallback: choose image_distort where people use a keyboard alone. What it stops and what it does not is under Auto check below.

Text answers are not case-sensitive. The plan of your account decides which types a key may request. In the JavaScript and Java SDKs, name them with ChallengeType.IMAGE_DISTORT, ChallengeType.MOTION_NOISE, ChallengeType.SLIDE_PUZZLE, ChallengeType.ANIMAL_JUMP, ChallengeType.OBJECT_ROTATE and ChallengeType.AUTO_CHECK.

See every captcha, with real samples

Limits and security

  • Challenges and tokens expire after two minutes, and each works once.
  • Behaviour check: with every answer the SDKs send how the pointer moved and how the answer was typed (never the keys), and from 1.3.0 a proof of work and three hints about the browser. The service also compares the address and User-Agent of the answer with those that fetched the challenge. An answer a script clearly gave, such as one typed in by a script, faster than anyone could, with a wrong proof of work or from an HTTP library, is refused even when right. Others get a verdict in /siteverify: accept human, refuse not_measured (no behaviour data was sent: an SDK older than 1.2.0 or a hand-written integration), and decide about suspicious per form, refusing it for sign-up and login.
  • Allowed domains and IP addresses: on a key's page, list the websites that may use the key (shop.example.com, *.example.com for its subdomains, localhost:3000) and, if you like, the addresses or networks (such as 203.0.113.0/24). With no domains any website may use it, with no addresses every address may; 0.0.0.0 also allows every address.
  • Resetting a secret key keeps the previous one valid for 24 hours, or until you revoke it, so servers can switch without downtime.
  • Each account has a daily quota of successful verifications, all its keys together; the pricing page lists the quota of every plan. It resets at 00:00 GMT+7 (17:00 UTC), and once it is used up new challenges are refused until then. An automatic pass of auto_check counts like a right answer; a visitor who falls back and solves the fallback counts once.
  • Rate limits, per minute: 30 challenges per IP address and 600 per key, 60 answers per IP address, and 1,200 /siteverify calls per secret key. An address with more than 20 wrong answers in 10 minutes is refused until those 10 minutes are over; an auto_check that falls back is not a wrong answer unless it was judged automated. Over a limit the reply is 429 RATE_LIMITED, with Retry-After in seconds. In front of the services, api.waucaptcha.com takes at most 120 requests a minute from one address.
  • Scraping check, per key and day: a key that fetched at least 500 challenges with fewer than 10% answered, or with at least 200 answers of which fewer than 10% were right or more than half automated, is flagged and throttled to 60 challenges a minute until midnight (GMT+7). Only a key with at least 5,000 challenges in a day and fewer than 5% answered is suspended. Either way its owner can request a review on the key's page. Fetch a challenge when the widget is shown, not ahead of time: challenges never answered count against the key.

Errors

In the JavaScript SDKs, compare error.code with the ErrorCode constants, e.g. ErrorCode.SITE_KEY_INVALID; in Java, compare e.getCode() with the same constants of com.waucaptcha.ErrorCode.

CodeMeaning
SITE_KEY_INVALIDUnknown, paused or deleted site key.
SECRET_KEY_INVALIDUnknown, paused or deleted key, or a wrong secret.
DOMAIN_NOT_ALLOWEDThe page is not on one of the key's allowed domains.
ORIGIN_NOT_ALLOWEDThe caller's IP address is not among the key's allowed addresses.
CHALLENGE_TYPE_NOT_ALLOWEDThe account's plan does not include this challenge type.
CHALLENGE_TYPE_UNSUPPORTEDchallenge_type is not a known type.
CHALLENGE_NOT_FOUNDThe challenge expired or was already answered. The widget and <WauCaptcha /> load a new one by themselves.
CHALLENGE_ID_INVALIDchallenge_id is not one the service issues.
BEHAVIOR_REQUIREDThe key requires behaviour data and the answer came without it: update @waucaptcha-sdk/client, or pass a Behavior in Java.
API_KEY_SUSPENDEDSuspended by an administrator or by the scraping check.
ACCOUNT_BANNEDThe owner of the key was banned.
DAILY_QUOTA_EXCEEDEDThe account used up today's successful verifications.
RATE_LIMITEDToo many requests from this address or key; Retry-After says how many seconds to wait.
PAYLOAD_TOO_LARGEThe request body is over the limit of the endpoint.
INTERNALThe service failed; the details stay in its log. Try again.
ROUTE_NOT_FOUNDNo service handles the path; check the base URL.
UPSTREAM_UNAVAILABLEThe service is temporarily unavailable; try again later.
NETWORK_ERROR, TIMEOUT, INVALID_RESPONSE, INTERRUPTEDReported by the SDKs when no usable reply arrived; INTERRUPTED only by the Java SDK, when the waiting thread was interrupted.

Auto check

auto_check lets most visitors through without a puzzle, so be clear about what that rests on.

What a pass rests on

Every signal inside the browser, from the probes to the behaviour and the proof of work, can be faked by a determined bot that drives a real browser. So an automatic pass leans on three things such a bot cannot fake from inside the browser:

  • A puzzle this browser solved on your site before: the clearance, kept up to 7 days and good for at most 6 automatic passes an hour and 24 a day.
  • An address that does not belong to a cloud or hosting provider: an answer from one never passes automatically, whatever its clearance and score, and gets the fallback.
  • Caps per address: 30 automatic passes an hour, at most 5 of them without a clearance.

Strict or balanced

  • Strict: a visitor passes automatically only after solving one puzzle on your site in this browser. The strongest: the first visit always shows a puzzle.
  • Balanced: a first visit from a home or mobile address may also pass on its signals alone, up to 5 an hour per address, with the reason first_visit.
  • WAU Captcha runs in balanced mode.

What it stops

  • Plain HTTP scripts, headless browsers that do not hide themselves (navigator.webdriver, a HeadlessChrome User-Agent, no outer window size, WebGL drawn in software, notifications denied while the browser says it would ask) and stealth plugins that patch browser functions or rewrite the User-Agent or the language.
  • Bots in data centres, whatever they fake: they never pass automatically. Every pass also costs the client a proof of work of 18 bits, about 8 times that of the other types, and the same browser asking again is judged the same way.

What it does not stop

  • A determined attacker who solves puzzles, or pays people to, earns clearances: each buys at most 6 automatic passes an hour and 24 a day, in the browser that solved it. In balanced mode, one behind home or mobile addresses also gets up to 5 first visits an hour per address. Cloudflare and Google have far more data to judge with.
  • For sign-ups, logins and payments, refuse the reason first_visit on your backend, or use an interactive type for those forms.

What it costs real people

  • People on a VPN or a cloud desktop always see a puzzle: their addresses belong to cloud and hosting providers.
  • Clearing the site's data or a private window means one more puzzle, and so does a browser update: the clearance goes with the site's data and is tied to the browser's User-Agent.

The SDK sends the names of the checks that tripped (patched_natives, outer_zero, software_gl, notification_mismatch, touch_mismatch, no_hardware and no_plugins), navigator.userAgent and navigator.language, which every request carries in its headers already, the behaviour it records for every type, here on the whole page, and counts of how the mouse moves were made, never positions beyond what the behaviour check already sends. It stores one thing in the browser: the clearance, in localStorage under your site's origin, which goes back to WAU Captcha with auto_check answers and nowhere else. No fingerprint, canvas or WebGL output, fonts or plugins. On the service, Redis counts the automatic passes of each address for an hour, those without a clearance too, and the passes of each clearance for an hour and a day; the clearance itself is signed, not stored.

A visitor it is unsure of gets a challenge of the fallback type instead, slide_puzzle unless you name another, and is never told why. auto_check is as accessible as that fallback: choose image_distort where people use a keyboard alone.

Set data-challenge-type="auto_check" with data-fallback-type and data-appearance (always, or interaction-only to show the captcha only for the fallback or an error), or the props challengeType, fallbackChallengeType and appearance of <WauCaptcha />:

html
<div  data-wau-captcha  data-site-key="pk_…"  data-base-url="https://api.waucaptcha.com"  data-challenge-type="auto_check"  data-fallback-type="image_distort"  data-appearance="interaction-only"></div>

What your backend can check

/siteverify reports challenge_type auto_check for an automatic pass, and the fallback's type for a visitor who solved the fallback. behavior.reasons says how an automatic pass was earned: cleared, by a browser that solved a puzzle on your site before, or first_visit, on its signals alone. Refusing first_visit for sign-ups, logins and payments makes balanced mode as strong as strict where it matters:

javascript
const result = await wau.verifyToken(token);if (!result.success || !hostnameMatches(result.hostname, process.env.WAU_ALLOWED_HOSTNAMES)) {  throw new Error("Please solve the captcha.");}// Passed auto_check on its signals alone, without a puzzle: a sign-up asks for one instead.if (result.behavior.reasons.includes("first_visit")) {  // e.g. show the form again with challengeType slide_puzzle}

In the usage charts, the success rate of auto_check is the share of visitors who passed without a puzzle.

Read the auto_check guide

Limitations

What the service does not catch, so you can weigh it against your risk:

  • TLS (JA3, JA4) and HTTP/2 fingerprints: Traefik ends TLS in front of the services and does not pass them on.
  • auto_check: a real browser driven with human-like input passes the automatic check with a clearance earned by solving a puzzle, or in balanced mode as a first visit from a home or mobile address; for sign-ups, logins and payments, refuse first_visit or ask for an interactive type.
  • Paid IP reputation feeds: the service only keeps its own short history of each address.
  • slide_puzzle: image matching finds where the hole is; its value is in the drag, which must move like a hand.
  • animal_jump: a script that analyses the frames can find the highest jump; a random click passes 1 time in 25, but most of its value lies in the behaviour and timing checks.
  • object_rotate: a script trained on the 10 objects could learn which way each one faces; random presses pass about 1 time in 64, but most of its value lies in the behaviour and timing checks.
  • motion_noise: a script that compares the frames can bring the characters out; it stops tools that read a single picture.
  • Text challenges: a model trained on these images can read many of them. Each challenge can be answered once, so a code cannot be brute-forced, and the per-address limits slow down guessing across challenges.
  • Origin and the browser hints can be forged by a script outside a browser.
  • No CAPTCHA stops a determined attacker on its own: use it together with rate limits and checks of your own on the actions that matter.