Errors

Siteverify error codes

Code	Meaning	Recommended handling
`missing_input_response`	No valid response was supplied.	Ask the visitor to complete verification.
`invalid_input_response`	Response is malformed or does not belong to the authenticated site.	Reset the widget and obtain a fresh response.
`timeout_or_duplicate`	Response expired or was already consumed.	Reset and verify a new response.
`invalid_secret`	Secret is missing, invalid, or revoked.	Fix backend configuration; never expose details to the visitor.
`site_disabled`	Site or credential is unavailable.	Check site configuration or contact support.
`action_mismatch`	Verified action differs from the expected action.	Reject the operation and review integration configuration.
`hostname_mismatch`	Verified hostname differs from the expected hostname.	Reject the operation and review domains/routing.
`invalid_idempotency_key`	The key conflicts with another response or request.	Generate a key scoped to one business attempt.
`rate_limited`	Verification limits were exceeded.	Respect `Retry-After`; apply backoff.
`service_unavailable`	Security state cannot be proven safely.	Fail closed and offer a retry path.

The widget’s error event includes a sanitized code and message:

invalid_sitekey
invalid_action
config_failed
config_parse_error
network_error
challenge_parse_error
challenge_unsupported
solve_failed
redeem_failed
invalid_solution
invalid_expires
unknown

Show the visitor a simple retry message. Keep the error code and HumanPass request ID in bounded application telemetry, but never log secret keys or response tokens.

Public service codes

Browser data-plane failures may also include stable HPxxxx request codes. These are diagnostic identifiers, not proof of successful verification. Include the code and request ID when contacting support.

Fail closed

If your application cannot determine that success is exactly true, reject or postpone the protected operation. Do not treat a network timeout, malformed JSON, unknown code, or widget visual state as success.