WeChat Mini Program Request Legitimate Domain: Configuration Requirements and Troubleshooting Online Request Failures

There is a particularly typical class of issues in Mini Programs: everything works fine in the development tools and during real-device previews, but requests fail once deployed to the online experience or release versions. The code hasn’t been changed, the server is functioning normally, and the problem lies solely on the Mini Program side.

In the vast majority of cases, this points to the request allowed domains configuration—Mini Programs do not allow requests to undomained domains. This is a platform-level mandatory constraint, beyond what your code or server can control.

Mandatory Requirements for Allowed Domains

These six conditions are linked by an “AND” relationship—if any single condition is not met, the request will be blocked. Furthermore, the blocking occurs at the platform level, so the server sees no request logs, resulting in a “silent failure.”

Additional Certificate Requirements

Having HTTPS alone is insufficient; the certificate itself must also meet specific requirements:

• TLS version must be 1.2 or higher: Versions 1.0 and 1.1 will be rejected
• Certificate chain must be complete: Browsers can automatically fill in missing intermediate certificates, but Mini Programs cannot

# Verify TLS version
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null

# Verify if the certificate chain is complete (critical: look for "Verify return code: 0")
openssl s_client -connect api.example.com:443 -servername api.example.com 
  -verify_return_error </dev/null

# Check which domains the certificate covers
openssl s_client -connect api.example.com:443 -servername api.example.com </dev/null 2>/dev/null 
  | openssl x509 -noout -ext subjectAltName

You must include -verify_return_error. Without it, openssl attempts to complete the certificate chain itself, which may show success even if the server configuration is flawed—meaning you won’t be able to reproduce the Mini Program’s failure.

Configuration Location and Modification Restrictions

1. Log in to the WeChat Official Platform
2. Navigate to “Development” → “Development Management” → “Development Settings”
3. Under “Server Domain Names,” enter the valid domain(s) for request
4. After saving, you must republish the mini program for the changes to take effect

Two easily overlooked points:

• There is a limit on the number of modifications; avoid frequent changes. Enter all required domains during the planning phase.
• Republishing is required after changes for them to take effect; saving without publishing means no change has been applied.

Troubleshooting Commands

# ① Verify protocol and port
curl -I https://api.example.com/ 2>&1 | head -3

# ② Check TLS version and certificate details
curl -sSv https://api.example.com/ 2>&1 | grep -iE 'TLS|SSL connection|subject:|issuer:'

# ③ Verify the completeness of the certificate chain (exit code must be 0)
openssl s_client -connect api.example.com:443 -servername api.example.com 
  -verify_return_error </dev/null 2>/dev/null | grep -i 'verify return'

# ④ Simulate the mini program's behavior without automatic chain completion to view the actual chain
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null

# ⑤ Check if the domain name is registered/filed (for domestic entities)
whois example.com | grep -iE 'status|registrar'

Decision Tree

Mini program online request fails
├─ Works in DevTools, fails online
│  ├─ "Ignore domain validity check" was enabled → DevTools bypassed validation, but online environment will not
│  │                           → Review the configured valid domains for request
│  └─ Not enabled, still failing            → See below
├─ Is the domain HTTPS + port 443?
│  └─ No                    → Update the API address; only port 443 is allowed
├─ Does the domain contain an IP address or path?
│  └─ Yes                      → Keep only the domain name itself
├─ Is the certificate chain complete (-verify_return_error)?
│  └─ Exit code is non-zero              → Configure fullchain on the server side
├─ Is TLS ≥ 1.2?
│  └─ No                    → Adjust ssl_protocols on the server side
└─ Has the domain completed ICP filing?
   └─ Not filed                  → Complete the filing before integration

Scenario Analysis: Works in DevTools, but all requests fail on real devices

Symptom: A mini program works perfectly with API calls during the development phase, but all network requests fail after submitting the experience version. The console error messages are vague, simply indicating that the request failed.

1. First, distinguish between a domain issue and a certificate issue → Both can cause request failures, but the troubleshooting approaches differ significantly. First, determine whether the failure occurs during the handshake phase or after the request is sent.
2. Verify if the requested domain is in the allowed list → During development, the “ignore domain validity check” option was likely enabled, whereas the live environment enforces strict validation. The actual requested domain may not have been added to the allowed list.
3. Confirm protocol and port requirements → The platform requires standard HTTPS ports and does not accept self-signed certificates. The test URL used at the time included a custom port.
4. Verify the certificate on the server using the command line → After adding strict validation, a non-zero result indicates that the intermediate certificate is missing. Browsers will automatically complete the chain, but mini-program clients will not.
5. Fix the server-side certificate chain and update the domain configuration in the management console → Changes are required on both sides: ensure the server has the complete certificate chain, and configure the correct request domain on the platform side.
6. Re-verify using real devices and multiple network environments → Do not rely solely on development tools; the validation rules on real devices differ from those in the development environment.

# Server-side: Check if the certificate chain is complete (return code must be 0)
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 
  -verify_return_error 2>&1 | grep -E 'Verify return code|depth'

# Check if the protocol version meets requirements
echo | openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 2>&1 
  | grep -E 'Protocol|Cipher'

# Must use standard port 443; custom ports are not accepted
curl -sS -o /dev/null -w '%{http_code}n' https://api.example.com/path

Root Cause: The lenient validation in the development environment masked two actual issues—the requested domain was not added to the allowlist, and the server’s certificate chain was incomplete. Neither issue triggered an error in the development tools.

Two Key Takeaways:

• The “skip validation” option in the development environment is only a local setting; real devices always enforce strict rules. Therefore, before going live, you must test with a real device using production configurations. Do not rely on results from development tools.
• When troubleshooting such failures, first determine whether the issue lies with domain configuration or the certificate chain. The distinguishing factor is at the handshake stage: if the domain is not in the allowlist, the request is typically blocked directly; if it is a certificate issue, it manifests as a handshake failure.

8 Common Pitfalls

1. “Skip Validation” enabled in DevTools: Everything looks green locally, but red online. This is the most frequent cause.
2. Interfaces include a port number: Only port 443 is supported; all other ports are rejected.
3. Using IP addresses instead of domain names: Not supported.
4. Including paths in registered domains: Only register the domain name; append the path during the request.
5. Incomplete certificate chain: Browsers can auto-complete the chain, but mini-programs cannot. You must provide the full chain.
6. Outdated TLS versions: Support only TLS 1.2 and 1.3; do not leave room for fallback to older versions.
7. Using self-signed certificates: These are not trusted, even in test environments.
8. Failing to redeploy after changing configurations: Saving changes does not mean they take effect immediately.

Real Customer Feedback (From Reviews and Inquiries for Similar Products on Cloud Marketplaces)

The following excerpts are taken from real buyer reviews and inquiries for similar operations and maintenance services listed on Alibaba Cloud, Tencent Cloud, and Huawei Cloud marketplaces (service providers include our store and competitors; these are provided solely as genuine feedback references and do not constitute fictitious tickets from this site):

s****2 Rating: 5.0 on 2023-02-28 11:04 Mai****8 Rating: 5.0 on 2020-06-29 17:44 4****6 Rating: 5.0 on 2019-01-07 14:56

a****8 Rating: 5.0 on 2025-08-22 14:43 r****8 Rating: 5.0 on 2025-05-22 15:34 t****c Rating: 5.0 on 2025-04-18 13:58 Cai****Kang Rating: 5.0 on 2024-08-31 12:05 2****2 Rating: 5.0 on 2024-02-21 11:08