Troubleshooting · Docs

Start with the reason #

Every refusal carries a reason, in one of two places:

In the browser, a refused issuance rejects execute with a BlockAltError whose reason says why (for example origin_denied). Log error.code and error.reason in your page while you debug. BlockAlt counts these refusals per site, minute and reason instead of logging each request.
On your server, every siteverify answer carries a reason and an id, and the console's decision log keeps these decisions for seven days.

If neither shows a refusal, the request never reached BlockAlt: look at your page's console (CSP, network) or your server's logs (timeouts, wrong URL).

Symptoms #

Symptom	Likely cause	Fix
Browser error `refused`, reason `origin_denied`	The page's exact origin (scheme, host, port) is not listed for the site	Add it in the site settings and publish
Browser error `refused`, reason `domain_unverified`	The hostname's TXT record is missing or not checked yet	Add `_blockalt.<hostname>` with the console's value and select Verify
Browser error `invalid_config`	`configPublicKeys` is outdated or mistyped, or the action is not configured	Copy every key again from the console or `GET /v1/keys`; check the action name
Nothing happens on submit; a CSP report in the browser console	Your Content-Security-Policy blocks the script or its requests	Add the CSP entries
Every verification is `invalid_token`	The token field is not sent, or is renamed on the way	Log the length of the received token (never the token) and compare names
`expired_token` after a slow form	The token was requested at page load	Call `execute` in the submit handler, or use `prepare`
`already_used` on a double click or a retry	The same token was verified twice	Disable the button while submitting; retry with an `idempotencyKey`
`wrong_hostname`	The server sends a different hostname, upper case, or with a port	Send the page's bare hostname in lower case
`wrong_action`	Browser and server use different action names	Use one constant per route on both sides
`stale_config` right after publishing	Tokens issued before the new version	Expected for a few seconds; the visitor retries
HTTP 401 `invalid_secret`	Wrong, revoked or whitespace-padded secret	Check the environment variable; create a new key if needed
HTTP 429 `rate_limited`	Too many verifications from your server, or a visitor over the site's rate	Back off; raise the site's rate setting if real visitors hit it
Everything passes with `unpaid`	The workspace has no credit left	Top up; see billing
Everything passes with `paused`	Protection is paused for the site	Resume it in the console
Everything fails with `rule_blocked`	A rule blocks the action, or all issuance (lockdown)	Lift the rule in the site settings
Everything fails with `suspended`	BlockAlt support suspended the site or its workspace for abuse	Read the note in the console and reply to support's email

Still stuck #

Write to support@blockalt.click with the site's public key, the time, and the id of a siteverify answer or the reason shown in the decision log. Never send a secret key or a visitor's token.