A very large (725-page) GitBook docs site with genuinely good agent affordances (llms.txt, per-page .md exports, a live quarterly roadmap) undermined by uncontrolled duplication: published draft copies, three near-identical page trees that are already diverging, and headline claims that contradict each other on the same page.
1. Connector count contradicts itself across pages — and within a single page (critical)
Problem: The Payment Suite page's intro bullet says "Unified API and no-code integrations for all 60+ payment processors", while a card on the same page says "Integrate with more than 200+ Connectors enabling 150+ payment methods". The Connectors Integration page and llms.txt descriptions repeat "200+ connectors". The GitHub README states a third figure: "Hyperswitch integrates with 100+ payment processors out of the box."
Consequence: A developer (or an AI agent summarizing the docs) cannot answer the most basic evaluation question — how many processors does this orchestrator actually support — without picking one of three conflicting numbers. Agents ingesting llms.txt will surface whichever page they hit first, so downstream answers are inconsistent by construction. "60+ processors" vs "200+ connectors" may reflect a real distinction (processors vs all connector types), but nothing on the page says so.
The fix: Pick one canonical figure per concept (payment processors vs total connectors vs payment methods), define the distinction once, and reference it everywhere — including the GitHub README. Remove the redundant "more than 200+" phrasing.
2. Unfinished "Copy of ..." draft pages are published in the live navigation (critical)
Problem: Two pages titled literally "Copy of Subscriptions" and "Copy of Standalone 3D Secure (via Hyperswitch)" are live, indexed in llms.txt, and sit in the nav next to their originals. The 3DS copy has already drifted from the original: the copy links supported authenticators to while the original links to , and sentences differ ("This is effective in" vs "This helps in effective").
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
Consequence: Developers can't tell which version is authoritative. AI agents can't either — they'll retrieve both, and where the copies disagree they fail silently, citing whichever they ranked higher. Publishing editor scratch copies also signals that no one reviews what actually ships in the nav.
The fix: Unpublish the "Copy of" pages (or merge any intended edits into the originals and delete the copies). Add a pre-publish check that blocks page titles matching Copy of *.
3. Three near-identical documentation trees for the same integration content, already diverging (critical)
Problem: llms.txt reveals whole page trees duplicated with identical titles and descriptions — e.g., "React with REST API Integration", "Error Codes", "Headless SDK", "Customization", Payouts and Split Settlement guides all exist in two or three parallel paths. A diff of the two React integration pages shows they are not synchronized copies: one has "Follow the Server Setup section" as a link, the duplicate has the same sentence with the link stripped ("Follow the Server Setup section."), plus missing figures and drifted heading levels.
Consequence: Every future edit now has to land in two or three places, and evidently doesn't — the copies are already inconsistent. Developers land on different versions from search and get subtly different instructions; agents indexing llms.txt see ~2-3x the pages with no canonical marker, wasting context and producing conflicting citations.
The fix: Choose one canonical tree per topic and make the others GitBook redirects (the site already uses 307 redirects extensively), or use synced content blocks. At minimum, add canonical links so agents and search engines can dedupe.
4. Webhook signing key is named two different ways on the page that defines it (significant)
Problem: The signature section introduces the key as payments_response_hash_key ("you can specify a secret key in the payments_response_hash_key field"), then the generation and validation steps both reference payment_response_hash_key (no "s"). The troubleshooting bullet is also garbled: "If your machine does't support HMAC-SHA256, you can use x-webhook-signature-256 header, which uses the HMAC-SHA256 algorithm" — the condition should read HMAC-SHA512, otherwise it says "if you don't support X, use X." There's also "signatured is generated."
Consequence: Webhook signature verification is exactly the code a developer writes from this page. A wrong field name means they configure or look up the wrong profile field and every signature check fails; the swapped SHA-256/512 condition compounds the confusion when they hit the troubleshooting section to debug it. An agent generating verification code from this page will propagate the wrong field name verbatim.
The fix: Standardize on the actual API field name everywhere on the page, fix the troubleshooting bullet to "if your system doesn't support HMAC-SHA512, use x-webhook-signature-256", and correct the typos.
5. React quickstart code references state that no step ever creates (significant)
Problem: Step 2.4's useEffect calls setClientSecret(data.clientSecret), but the only state-setup step (2.6, "Setup the state") declares just message and isLoading — clientSecret/setClientSecret are never declared anywhere on the page. Step 2.7 ends with "You can find the API for these methods here." where "here" is plain text with no link. The import in 2.2 is hyperElements (lowercase) while the JSX in 2.5 renders <HyperElements>. Step 2.5 also links out to a legacy docs URL (hyperswitch.io/docs/sdkIntegrations/unifiedCheckoutWeb/customization), and the "Demo App" download points to a personal GitHub account (github.com/PritishBudhiraja/...) rather than the juspay org.
Consequence: Assembling the page's snippets in order produces code that doesn't compile (setClientSecret is not defined, wrong import casing). This is precisely the copy-paste failure mode for AI coding agents: each snippet looks complete, the composition is broken. The unlinked "here" leaves the hooks API undiscoverable, and a personal-repo demo app can vanish or rot without anyone at Juspay noticing.
The fix: Add const [clientSecret, setClientSecret] = useState("") to the state step (or 2.4), fix the import/JSX casing, restore the missing hyperlink, point the customization link at the current docs page, and move the demo app into the juspay org.
6. GitHub README links to a docs URL that 404s (significant)
Problem: The README's video-tutorial link, https://docs.hyperswitch.io/hyperswitch-open-source/overview/unified-local-setup-using-docker, returns HTTP 404 with no redirect (verified by direct request). The surrounding README links (/about-hyperswitch/payments-modules/..., /hyperswitch-open-source/account-setup/...) all target retired URL structures that only resolve through 307 redirect chains.
Consequence: The GitHub README is the single highest-traffic entry point for an open-source project. New contributors following the quickstart's "further help" link hit a dead page. Reliance on redirect chains for every other link means the next docs reorganization silently breaks the README again.
The fix: Update README links to the current canonical URLs (the working Docker page is /self-hosting/hyperswitch-open-source/readme-1/unified-local-setup-using-docker), and add a link checker to CI for README + docs cross-links.
7. Docs homepage deployment cards are mislabeled and interlinked wrong (significant)
Problem: The "Local Deployment (Helm charts)" card's action link reads "Set up Docker Locally →" and points to the exact same GitHub URL as the Docker card (github.com/juspay/hyperswitch-docs/tree/main/setup-hyperswitch-locally/run-hyperswitch.md) — a raw path in the docs source repo, not a docs page. The AWS/GCP/Azure Helm card is labeled only "Deploy on GCP or Azure →" despite the body naming AWS first. The card copy also contains the ungrammatical "who want view all available components."
Consequence: This is the first page of the docs. A platform engineer looking for the Helm path clicks "Set up Docker Locally" and lands in a GitHub source tree instead of the actual Helm guide that exists at /self-hosting/hyperswitch-open-source/deploy-on-kubernetes-using-helm. The strongest deployment content in the docs is unreachable from the card that advertises it.
The fix: Point the Helm card at the Kubernetes/Helm guide, relabel the links to match their targets ("Set up Helm Locally", "Deploy on AWS, GCP or Azure"), and route the Docker card to the in-docs Docker page rather than the source repo.
8. Internal GitBook plumbing leaks into published links (minor)
Problem: The Payments Flows page links its Vault reference to a draft-revision URL (https://docs.hyperswitch.io/~/revisions/wA01t1OV6BPUckMZ2Pvg/explore-hyperswitch/workflows/vault/...). The Overview page's architecture cards link to raw internal page IDs (/pages/P26kRLa2c4E3M1QHgf5U) that resolve only via redirects. The FAQ links to the API reference with a full Google Analytics cross-domain payload baked into the href (?_gl=1*1bcxxw7*_gcl_au*..., hundreds of characters).
Consequence: Revision-pinned links show readers a frozen draft instead of the living page (and break if the revision is pruned); /pages/<id> links and pasted tracking parameters survive in bookmarks, agent citations, and copied markdown, degrading link stability and leaking analytics state between users.
The fix: Sweep for ~/revisions/, /pages/, and _gl= in link hrefs during publish; relink to canonical published paths.
9. SDK Error Codes page documents messages, not codes (minor)
Problem: The web SDK's entire error reference is a 9-row table of Error Type / Error Message pairs — e.g. invalid_request_error / "Invalid promise", confirm_payment_failed / "An unknown error occurred". No stable error codes, no field indicating where the error surfaces (callback? promise rejection?), no handling guidance, and messages with placeholders like < parameter_name >.
Consequence: "Graceful handling" (the page's stated purpose) requires branching on stable identifiers; developers are left string-matching human-readable messages that can change. The server-side API reference has a proper error-codes page, which makes the client-side contract look abandoned by comparison.
The fix: Publish the SDK's actual error object schema (code, type, message), enumerate the codes, and show one handling example per error class.
What they do well
Best-in-class agent affordances for a GitBook site: llms.txt index, every page served as .md, and a queryable ?ask= endpoint per page.
Operational specifics most docs omit are concrete here: exact webhook retry schedule, per-connector test cards, rate limits (80 rps) and API-locking semantics, auth key types with prefixes.
Actively maintained: a current Q3 2026 roadmap with nine archived quarterly roadmaps, and a one-command local Docker setup.
Top 3 recommendations
Deduplicate: unpublish the "Copy of" pages and collapse the three parallel integration trees into one canonical tree with redirects — this is the root cause behind most drift.
Reconcile the 60+/100+/200+ connector figures into one defined, sourced number used across docs, llms.txt descriptions, and the GitHub README.
Add link and snippet CI: catch 404s from the README, revision-pinned and /pages/ hrefs, and non-compiling quickstart code (the React page's undeclared clientSecret) before publish.