Article

Why Your Site Breaks in China: The Blocked-API Playbook

September 28, 2026

Your site loads fine in New York and London. In Shanghai, the map stays gray, the video player spins, and the checkout button does nothing. Your hosting is not the problem. A third-party script in your <head> is.

This article is a dependency-by-dependency playbook. For each blocked or unreliable API, you get the failure mode your China visitors see and the replacement path. If you need the broader performance picture — transit, DNS, CDN architecture — start with the companion article on why your site is slow in China.

How to tell blocked from slow

Two failure classes. In the first, everything loads late — the entire page is slow. That is a transit, DNS, or CDN problem: the requests reach the server, but the path is long or congested. The slow-in-China article covers that class.

In the second class, most of the page renders but specific parts never appear. An embedded map stays gray. A video player spins forever. A font never loads and the layout shifts. A form submit hangs. These are dependency failures — individual third-party calls that time out because the endpoint is blocked or unreachable from mainland China.

The diagnostic is the browser network tab from a mainland session. Open DevTools, load the page, and sort requests by timing. Domains that show pending or timed-out connections are your blocked dependencies. Classify each external call: works, slow, or blocked. Each blocked API has its own replacement path. For the full measurement procedure — mainland test-point services, per-run recording, and benchmark numbers — see how to test your website from China. The 10-point China readiness diagnostic carries the dependency checks too.

Mainland hosting does not fix this. Moving your server to Shanghai makes your HTML fast, but it does not make Google Maps load. Blocked dependencies must be replaced or proxied, dependency by dependency.

The blocked-API dependency audit

Every external call your page makes is a dependency. The audit lists them all and classifies each one.

Start with the network tab from a mainland browser session. List every third-party domain that appears. For each domain, note whether the request completes, loads slowly, or times out entirely. Group them by function: maps, video, fonts, icons, tag managers, authentication, payment, forms.

Common categories that surface in the audit:

• Map and location APIs. Google Maps is blocked or unreliable in mainland China. The map tiles never load, and the JavaScript SDK hangs.
• Video embeds. YouTube and Vimeo fail or time out from China, leaving empty embed areas and dead video players.
• Font, icon, and tag-manager endpoints. Global font CDNs, icon libraries, and tag-manager scripts can all fail behind the firewall. These are architecture decisions, not performance tweaks.
• Authentication and payment APIs. Login and payment endpoints that China visitors cannot reach. Global payment gateways fail behind the firewall. WeChat Pay is the canonical China-accessible replacement.

The audit output is a table: every external domain, its function, its status from mainland China, and the replacement or proxy path. That table drives the work. Our infrastructure service includes a dependency audit to identify scripts and APIs that fail behind the firewall. For a filterable view of the verdicts already banked, the China dependency checker condenses each one into a status row.

Dependency-by-dependency playbook

Maps

Status: Google Maps is blocked or unreliable in mainland China.

Failure mode: Map tiles stay gray or never load. The JavaScript SDK hangs waiting for Google's servers. The page renders around the gap, but the map area is empty.

Replacement path: Use Amap (Gaode Maps) or Baidu Maps. Both are China-accessible replacements serving tiles, routing, and places data. For WeChat Mini Program integration, Tencent Location Services (lbs.qq.com) is a third domestic option. Switching means replacing your map provider SDK, not just a URL — plan for component-level changes in the map integration.

Video

Status: YouTube and Vimeo fail or time out from mainland China.

Failure mode: The embedded player shows a loading spinner that never resolves. The iframe request to the video host never completes. The page renders around the gap, but the video content is absent.

Replacement path: Use domestic video hosts. Upload to a China-accessible platform and embed its player. Bilibili operates an official external embed player (player.bilibili.com) suitable for web embeds. For production video delivery, host files on mainland CDN-backed storage and use a domestic player. The video asset itself must reside on servers reachable from mainland China.

Fonts & tag managers

Status: Global font CDNs, icon libraries, and tag-manager endpoints are slow to unreachable from mainland China.

Failure mode: A render-blocking <link> to a font CDN in the <head> stalls the entire page — nothing renders until the request times out. An async font load causes a flash of unstyled text or a layout shift when the font never arrives and the browser falls back. Missing icon fonts leave blank squares. A blocked tag-manager script prevents analytics, A/B tests, and any logic it gates from firing.

Replacement path: Self-host font files on your mainland server. Download the font files, serve them from your own domain, and update the @font-face declarations to point locally. For Google Fonts specifically, Google operates mainland-facing mirror domains: fonts.googleapis.cn serves the CSS API and fonts.gstatic.cn serves the font binaries. You can swap the embed URL to the .cn mirror, but self-hosting removes the external dependency entirely. Always list a fallback web-safe font and use font-display to control behavior when the font is unavailable. For how mainland delivery of your own assets works, see the China CDN prerequisite guide. For tag managers, evaluate whether you need the global container at all for China traffic — a China-specific tag path may be cleaner.

reCAPTCHA & forms

Status: Google's default reCAPTCHA wiring loads from www.google.com/recaptcha/ and www.gstatic.com/recaptcha/ — both Google domains unreachable from mainland China.

Failure mode: The CAPTCHA widget never renders. The form appears functional, but the verification checkbox or invisible challenge does not load. Users in China cannot submit the form.

Replacement path: Google's official FAQ states that when www.google.com is unreachable, use www.recaptcha.net. Replace www.google.com/recaptcha/api.js with www.recaptcha.net/recaptcha/api.js and all www.google.com/recaptcha/ instances likewise. This is the documented global-fallback domain. For a domestic CAPTCHA product, Alibaba Cloud CAPTCHA is an official alternative designed for mainland reach. The replacement is not drop-in — the server-side verification call changes, and the widget API differs.

Firebase

Status: Firebase depends on Google-hosted endpoints with no official mainland-China availability commitment.

Failure mode: Firebase SDK modules load from www.gstatic.com/firebasejs/... — Google-owned endpoints. If these time out, any feature built on Firebase — authentication, real-time database, cloud messaging, hosting — fails for China visitors. The failure is easy to miss: the page looks fine until a visitor tries the affected feature.

Replacement path: Treat Firebase as a dependency to audit and replace or proxy. firebase.google.cn is a live official Google-hosted mirror site, but Google publishes no mainland-China availability statement for Firebase services. Firebase Hosting is described only as a "global CDN" with no documented mainland carve-out. Do not assume any Firebase service works in China without testing from a mainland session. For each Firebase feature you use, identify a mainland-reachable alternative: self-hosted auth, a mainland-hosted database, or a domestic push-notification service. Proxy setups exist but add latency and operational complexity.

Stripe & checkout

Status: Global payment gateways fail behind the firewall.

Failure mode: The checkout page loads, but the payment form or redirect never completes — the gateway's client-side calls hit endpoints that fail behind the firewall. The customer sees a hanging or broken checkout.

Replacement path: WeChat Pay is the canonical China-accessible replacement for payment flows. Stripe's official docs list WeChat Pay as a supported payment method for cross-border acceptance — Stripe merchants can accept WeChat Pay from Chinese customers, with one-time payments supported (subscriptions not yet) and CNY presentation available. This is a cross-border path: a Stripe merchant accepting Chinese wallets, not a mainland acquiring setup. For a China-native checkout experience, integrate WeChat Pay directly. The vehicle — Mini Program, H5 page, or native app — shapes the integration pattern, and a native app is itself a filing object when its backend resolves to mainland servers — when a native app (or API backend) needs an APP filing.

Three pointers follow from that. The product-side choice between surfaces is covered by our WeChat ecosystem service and the Mini Program vs H5 comparison. Merchant onboarding — who can apply on which path, which documents, and how settlement works — is laid out in WeChat Pay for foreign companies: acceptance paths and requirements. And the compliance prerequisites of a mainland-hosted checkout sit with the ICP & compliance service.

Replace vs. proxy vs. hybrid

Most brands keep their global website and add a China path. You do not need to re-platform. The question for each dependency is: replace it, proxy it, or run both paths.

Replace means swapping the blocked dependency for a domestic equivalent. Google Maps becomes Amap. YouTube becomes a domestic video host. Stripe checkout becomes WeChat Pay. This is the cleanest path. The replacement serves China traffic from mainland-reachable infrastructure, and you maintain the global version for everyone else.

Proxy means routing the blocked request through a mainland-reachable intermediary. A reverse proxy on your mainland server fetches the external resource server-side and serves it to China visitors. This works for fonts, icons, and some static API calls. It does not work for interactive SDKs that require direct client-side connections to the original service — map SDKs, payment SDKs, real-time databases. Proxy setups add latency, caching complexity, and a maintenance burden.

Hybrid means running two code paths: the global stack for international visitors, and a China-specific build that swaps or removes blocked dependencies. A conditional loader detects the visitor's location and serves the appropriate dependency set. This is the most common production pattern for sites with significant traffic from both regions.

The decision rule: if the SDK requires direct client-side access to the foreign service, replace. If it is a static asset, proxy or self-host. If the feature is optional for China traffic, remove it from the China path entirely.

Which dependency fix fits your situation

The replacement path changes shape depending on which dependency fails and how it fails. The matrix below maps eight common situations to the symptom your China visitors see, the verification step, and the fix path.

Note: mainland hosting fixes none of the eight rows — moving your server to Shanghai makes your HTML fast, but it does not make Google Maps load. The 10-point China readiness diagnostic carries the dependency checks at items 5–7.

FAQ: Blocked APIs in China

Next steps

The dependency audit is the first step. Once you know which endpoints fail, each one has a defined replacement path — maps, video, fonts, forms, checkout, backend services.

Bring your site URL and your network-tab output. We will run the dependency audit, classify each blocked endpoint, and build the replace-or-proxy plan for your China path.

If the audit reveals you need mainland hosting, plan the filing window early.

Start with the infrastructure service or the 10-point China readiness diagnostic, or email hello@chinagateway.pro.