Every stable error code the Checkbox API returns, with its HTTP status, type and meaning. Error responses link here through doc_url.

Every error response has the shape { "error": { type, code, message, param?, doc_url, request_id, next_action? } }. Branch on code, not on message: codes are part of the contract and are never renamed or reused, while messages may change. When next_action is present, follow it.

#Codes

#parameter_invalid

HTTP 400 · invalid_request_error

A parameter has an invalid value; param names it.

#parameter_missing

HTTP 400 · invalid_request_error

A required parameter is missing; param names it.

#parameter_unknown

HTTP 400 · invalid_request_error

The request has a parameter this endpoint does not accept.

#body_invalid_json

HTTP 400 · invalid_request_error

The request body is not valid JSON.

#url_not_allowed

HTTP 400 · invalid_request_error

A URL points to a private, local or otherwise unreachable address.

#api_version_invalid

HTTP 400 · invalid_request_error

The Checkbox-Version header names an unknown API version.

#idempotency_key_invalid

HTTP 400 · idempotency_error

The Idempotency-Key header is empty or longer than 255 characters.

#idempotency_key_reused

HTTP 400 · idempotency_error

The Idempotency-Key was already used with different parameters within 24 hours.

#test_key_missing

HTTP 400 · invalid_request_error

A Stripe test run needs a Stripe TEST-mode key stored for the site (createTestCredential).

#test_key_not_test_mode

HTTP 400 · invalid_request_error

The billing key is a live-mode (or malformed) key; test runs only accept test-mode keys (rk_test_… / sk_test_…).

#test_key_rejected

HTTP 400 · invalid_request_error

Stripe rejected the test-mode key or it lacks a permission test runs need; message names it.

#authorization_pending

HTTP 400 · invalid_request_error

Device login: the human has not approved yet. Keep polling createDeviceToken every interval seconds.

#slow_down

HTTP 400 · rate_limit_error

Device login: polling too fast. Add 5 seconds to the interval and keep polling.

#expired_token

HTTP 400 · invalid_request_error

Device login: the device code expired (15 minutes) or was already used. Start again with createDeviceAuthorization.

#device_code_invalid

HTTP 400 · invalid_request_error

Device login: the device code is unknown.

#access_denied

HTTP 403 · permission_error

Device login: the human clicked Deny. Do not retry without asking them.

#api_key_missing

HTTP 401 · authentication_error

No API key was provided (Authorization: Bearer ck_…).

#api_key_invalid

HTTP 401 · authentication_error

The API key is unknown, revoked or expired.

#publishable_key_not_allowed

HTTP 403 · permission_error

A publishable key (pk_…) cannot call this endpoint; use a secret key on your server.

#origin_not_allowed

HTTP 403 · permission_error

A publishable-key request came from a page (Origin) that is not on one of the site's domains (base URL or checkout URL).

#insufficient_scope

HTTP 403 · permission_error

The restricted key lacks the scope this endpoint needs.

#insufficient_role

HTTP 403 · permission_error

The key (or the person who created it) does not have a role that allows this action.

#account_not_activated

HTTP 403 · permission_error

Live mode needs an activated account: verify the domain of one of your sites (or use a test key).

#test_mode_domain_unverified

HTTP 403 · permission_error

Test mode only scans, monitors, fetches and test-runs localhost or domains the account has verified; verify the domain (createDomainVerification) or send the HTML instead.

#test_mode_scan_budget_exhausted

HTTP 429 · rate_limit_error

The daily test-mode scan budget for sites on unverified domains is used up; verify the domain (createDomainVerification) to lift it.

#account_suspended

HTTP 403 · permission_error

The account was suspended by Checkbox staff; contact support.

#resource_missing

HTTP 404 · invalid_request_error

No object with this id exists in this mode of the account.

#route_not_found

HTTP 404 · invalid_request_error

No such endpoint. See /v1/openapi.json for the list.

#resource_conflict

HTTP 409 · invalid_request_error

The object is in a state that does not allow this action.

#scan_already_queued

HTTP 409 · invalid_request_error

A scan of this site is already queued or running.

#consent_reference_locked

HTTP 409 · invalid_request_error

The consent already carries a different customer_reference; references are set once and never changed.

#test_run_in_progress

HTTP 409 · invalid_request_error

The site already has a queued or running test run; wait for it (retrieveTestRun) or cancel it (cancelTestRun).

#idempotency_key_in_use

HTTP 409 · idempotency_error

A request with this Idempotency-Key is still being processed; retry shortly.

#resource_archived

HTTP 410 · invalid_request_error

The object is archived; restore it before changing it.

#body_too_large

HTTP 413 · invalid_request_error

The request body is too large.

#content_type_unsupported

HTTP 415 · invalid_request_error

Send JSON bodies with Content-Type: application/json.

#site_limit_reached

HTTP 403 · invalid_request_error

The account reached its fair-use site limit (default 25); contact support to raise it.

#webhook_endpoint_limit_reached

HTTP 403 · invalid_request_error

The account reached the maximum number of webhook endpoints (16 per mode).

#plan_required

HTTP 402 · invalid_request_error

Only when billing is enabled on this deployment: the feature needs a paid plan.

#rate_limit_exceeded

HTTP 429 · rate_limit_error

Too many requests; slow down and retry after the Retry-After header.

#feature_unavailable

HTTP 503 · api_error

The feature is not configured on this deployment (for example the database migration is missing).

#internal_error

HTTP 500 · api_error

Something went wrong on Checkbox's side. Retrying with the same Idempotency-Key is safe.

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.