docs: add an error reference for every widget-visible error - #59
Draft
HughParry wants to merge 1 commit into
Draft
docs: add an error reference for every widget-visible error#59HughParry wants to merge 1 commit into
HughParry wants to merge 1 commit into
Conversation
Documents each error message Procaptcha can display in place of the
widget, with the translated string, the stable translation key, the HTTP
status, and — for each — what it means, what causes it, and how to clear
it.
The set is derived from what actually reaches the screen (state.error.message
into Checkbox, and fallOverWithStyle for frictionless) rather than from the
locale file, which is much broader. Errors thrown inside providerRetry go to
console.error and never render, and PoW/puzzle submit returns
{ status: "ok", verified: false } with no message, so the IP-category block
reasons (VPN_BLOCKED, TOR_BLOCKED, ...) are deliberately excluded — they are
deferred to submit/verify time and belong with the siteverify ResultReason
values. API.FAILED_IP_VALIDATION is likewise omitted: validateSessionIP
unconditionally returns valid.
The six error Q&As in the FAQ now give a one-line answer and link into the
detailed section so the prose lives in one place. Corrects "Session not
found" to "No session found" (the actual string) and adds an entry for the
case where the widget fails silently to the console.
Incorrect CAPTCHA type is written around its real causes (direct API
integrations, old bundles, stale sessions, captchaType-pinning access rules)
rather than the data-captcha-type advice in captcha-types.mdx, which current
bundles ignore. That page needs a separate fix.
Claude-Session: https://claude.ai/code/session_01DLYQU7po3wAWsppeaUrU7b
✅ Deploy Preview for peaceful-pothos-9e62ce ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes prosopo/captcha-private#1350.
Adds
basics/error-reference, documenting every error message Procaptcha can display in place of the widget. Each entry gives the translated string, the stable translation key, the HTTP status, then What it means / What causes it / How to fix it.The page
Opens with how to read an error — the on-screen string is translated per visitor,
API.SITE_KEY_NOT_REGISTEREDnever is — and how to pull the key out of the Network tab. That last bit is necessary becauseerror-callbackreceives only the translatedmessage, not the key.Then a quick-reference table linking into four groups:
API.SITE_KEY_NOT_REGISTERED,API.INVALID_SITE_KEY,API.UNAUTHORIZED_ORIGIN_URL,API.INCORRECT_CAPTCHA_TYPE,WIDGET.INSECURE_CONTEXTCAPTCHA.NO_SESSION_FOUND,Cannot load CAPTCHAFrictionless response missing captchaType…(401),Forbidden: <request id>(403)CAPTCHA.PARSE_ERROR,API.BAD_REQUESTPlus a table of console-only failures (
No site key found,GENERAL.SITE_KEY_MISSING,DEVELOPER.PROVIDER_NO_CAPTCHA), since "the captcha just doesn't appear and there's no error" is a distinct support case.Scope: what reaches the screen
The list is derived from the render path —
state.error.messageintoCheckbox, andfallOverWithStylefor frictionless — not from the locale file, which is far broader. That excludes more than it includes:providerRetrygo toconsole.errorand never render.{ status: "ok", verified: false }with no message.VPN_BLOCKED,TOR_BLOCKED,DATACENTER_BLOCKED, …) are deferred to submit/verify time by design, so a blocked visitor still gets a captcha. They belong with the siteverifyResultReasonvalues, not here.API.FAILED_IP_VALIDATIONis unreachable at challenge time —validateSessionIPunconditionally returns{ valid: true }.Access-policy blocks and auto-ban both emit a bare
401 {error: "Unauthorized"}, which the widget's guard turns into the developer-ishFrictionless response missing captchaType; halting captcha mount. Documented as-is, because that is genuinely what a blocked visitor sees.FAQ
The six error Q&As now give a one-line answer and link into the detailed section, so the prose lives in one place. Also corrects
Session not found→No session found(the actual string) and adds an entry for the silent-console-failure case.Follow-ups, not in this PR
data-captcha-typeis documented but ignored.renderLogic.test.tsxasserts the bundle silently ignores it — the type is server-driven now — butbasics/captcha-types.mdxstill tells people to set it. TheIncorrect CAPTCHA typesection here is written around the real causes instead; that page needs its own fix.API.INTERNAL_SERVER_ERROR,API.UNKNOWN_ERRORandCAPTCHA.DECISION_MACHINE_DENIEDare referenced in code but absent fromlocale/src/locales/en/translation.json, so i18next would render the raw key. None are on a widget-visible path today, so they are not documented here, but they are latent.Verification
npm run buildpasses — 396 pages; the page builds for all locales via English fallback.npm run lint:linkcheck:nobuildreports no link issues; all 11 quick-reference anchors and the FAQ deep-links resolve against generated heading ids.npm run lintfails onmainalready, independently of this change: 2 eslint errors inscripts/lib/linkcheck/base/page.tsandsrc/components/starlight/Head.astro. CI will be red until those are fixed separately.lint:slugchecklikewise fails on 5 pre-existing stalebasics/context-awareness.mdxtranslations (the English page lives atadvanced/now).https://claude.ai/code/session_01DLYQU7po3wAWsppeaUrU7b