Sandbox (test keys)
Tasks created with a test key (nop_test_…) never reach a solver, are never charged and never appear in usage.
They behave like real tasks otherwise: same endpoints, same validation, same response shapes. Use them to build
and test integrations, and to run the examples in this documentation.
Answers
Section titled “Answers”| Type | Sandbox solution |
|---|---|
| Token types (reCAPTCHA, hCaptcha, Turnstile) | token = NOPTCHA_TEST_TOKEN_<task id>, user_agent = Mozilla/5.0 (Noptcha test) |
funcaptcha |
only token |
cloudflare.challenge |
cookies.cf_clearance = NOPTCHA_TEST_TOKEN_<task id>, user_agent |
image.text |
text = noptcha |
Image grids and image.funcaptcha |
objects = [0] |
Each task type page shows the exact sandbox answer in both APIs. The compatibility API returns
the same answer in its own field names (for example gRecaptchaResponse).
Simulating outcomes
Section titled “Simulating outcomes”Put a magic value in website_key (compatibility API: websiteKey), website_public_key (websitePublicKey) or
question:
| Value starts with | Outcome |
|---|---|
test-unsolvable |
fails with unsolvable (ERROR_CAPTCHA_UNSOLVABLE) |
test-timeout |
fails with timeout (ERROR_CAPTCHA_UNSOLVABLE) |
test-proxy-error |
fails with proxy_error (ERROR_PROXY_CONNECT_REFUSED) |
test-slow-<seconds> |
stays processing for that many seconds (at most 90), then succeeds |
In the sandbox the task is always created, and a failure is reported when you read the task: getTaskResult,
res.php, GET /v1/tasks/{id}, or the response of POST /v1/tasks when it waits. Live tasks of some types can also
fail in the create response itself (see Solving a task);
handle both. A test-slow-5 task is a good way to exercise polling and Prefer: wait.
Limits
Section titled “Limits”The sandbox has its own limits per organization, on top of the per-key limits (Rate limits):
| Limit | |
|---|---|
| Tasks created | 10 per second (429 rate_limited / ERROR_NO_SLOT_AVAILABLE) |
Tasks still processing (test-slow-…) |
20 (429 concurrency_limited) |
| Synchronous waits | 20 per API server; more return 202 at once |
These are starting values and may change.
What else is different
Section titled “What else is different”- Sandbox tasks carry
"sandbox": truein v1; the compatibility API returns an emptyip. - Results are kept for 10 minutes, like live tasks.
- Test keys see only sandbox tasks and live keys only live tasks.
GET /v1/usagewith a test key returns an empty report with"sandbox": true.- Balance endpoints return your organization’s real balance, which test tasks never change.