Troubleshooting Path for Mini Program API ‘Invalid Certificate’ Errors: From Server to Client

When a mini program reports an “invalid certificate,” the most challenging aspect is that this message does not specify exactly what is invalid. It could be due to an expired certificate, an incomplete chain, domain mismatch, insufficient TLS version, or even incorrect device time on the user’s phone.

The following troubleshooting steps follow the order of “server first, then client”—because the server is the only side you can fully control. Eliminate server-side issues first before investigating client-side factors.

Troubleshooting Path

① Is the Certificate Expired?

openssl s_client -connect api.example.com:443 -servername api.example.com 
  </dev/null 2>/dev/null | openssl x509 -noout -dates -subject

Check if notAfter has passed. Expiration is the most common and easiest issue to fix—simply renew the certificate.

② Is the Certificate Chain Complete?

# Key: -verify_return_error simulates a client that does NOT auto-complete the chain
openssl s_client -connect api.example.com:443 -servername api.example.com 
  -verify_return_error </dev/null 2>/dev/null | grep -i 'verify return'

# Check how many certificates the server actually returns
openssl s_client -connect api.example.com:443 -servername api.example.com 
  -showcerts </dev/null 2>/dev/null | grep -c 'BEGIN CERTIFICATE'

You must see Verify return code: 0 (ok). Any non-zero value indicates a chain issue; you need to configure the fullchain.

This is a high-frequency cause in mini program scenarios: browsers automatically complete intermediate certificates, but mini programs do not. Therefore, normal browser behavior does not guarantee correctness.

③ Does the Domain Match?

openssl s_client -connect api.example.com:443 -servername api.example.com 
  </dev/null 2>/dev/null 
  | openssl x509 -noout -ext subjectAltName

Confirm that the requested domain is listed in the subjectAltName. Common errors include:

• The certificate was issued only for www.example.com, but the request uses api.example.com.
• The certificate covers the root domain but not subdomains.
• A single-domain certificate is used across multiple subdomains.

Note: The Subject Alternative Name (SAN) is now the standard; CN is no longer checked. Checking only the CN will lead to incorrect conclusions.

④ Is the TLS Version Sufficient?

# Test separately (1.2 should succeed, 1.1 should fail)
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_1 </dev/null

Mini programs require TLS 1.2 or higher. The server should only allow TLS 1.2 and 1.3.

⑤ Is it a Self-Signed or Private CA Certificate?

openssl s_client -connect api.example.com:443 -servername api.example.com 
  </dev/null 2>/dev/null | openssl x509 -noout -issuer -subject

# For self-signed certificates, issuer and subject are identical

Self-signed certificates are never trusted by mini programs, even in test environments. You must use certificates issued by a trusted CA.

Client-Side Factors

If all server-side checks pass but users still report certificate errors, consider client-side factors:

Incorrect device time is the client-side factor most likely to be overlooked—it causes valid certificates to appear invalid, with symptoms identical to actual expiration.

Diagnostic method: If only a few users report errors and server-side checks are all normal, prioritize suspecting client-side factors.

Decision Tree

Mini Program Reports Invalid Certificate
├─ ① Is it expired?          → Check notAfter → Renew
├─ ② Is the chain complete?  → Non-zero with -verify_return_error → Configure fullchain
├─ ③ Does the domain match?  → Check subjectAltName (ignore CN)
├─ ④ Is TLS ≥ 1.2?          → Allow only 1.2/1.3
├─ ⑤ Is it self-signed?      → Switch to a trusted CA certificate
└─ All server-side checks normal
   ├─ Only a few users report → Client-side factors (device time/OS version/proxy)
   └─ Widespread reports      → Recheck deployment changes or recent certificate swaps

Scenario Analysis: Certificate Not Expired, Yet API Reports “Invalid Certificate”

Symptom: A domain providing APIs has a valid certificate, and tools show no errors when accessing it. However, some callers consistently receive “invalid certificate” errors, affecting only a subset of callers.

1. Determine which result to trust → Your own tools/browsers auto-complete chains;
   their “normal” status is not proof of chain completeness. This step determines whether further troubleshooting is meaningful.
2. Retest with strict validation → If the return code is non-zero, confirm the chain is indeed missing a level.
3. Count the certificates served by the server → Only the site certificate is present; the intermediate certificate was not included.
4. Verify if the domain is covered by the certificate → The extension fields do include it,
   ruling out “domain mismatch” as the cause.
5. Complete the chain and reload → Concatenate site certificate followed by intermediate certificate, then reload the service.
6. Re-verify based on caller behavior → Re-test without auto-completion,
   and ask the originally failing callers to retry.

# Strict validation: This is the only reliable way to judge
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 
  -verify_return_error 2>&1 | grep -E 'Verify return code|depth'

# Count how many certificates were served
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null 
  | grep -c 'BEGIN CERTIFICATE'

# Confirm the domain is within coverage
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null 
  | openssl x509 -noout -ext subjectAltName

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

Root Cause: The server lacked the intermediate certificate, resulting in an incomplete chain.
Different callers have varying levels of support for auto-completion, leading to contradictory results between clients that “can complete” and those that “cannot complete” the same configuration.

Two key takeaways:

• For certificate issues, start troubleshooting with strict validation.
  Using browsers or loose validation methods only reinforces the conclusion “it works for me,” while the problem persists.
• After fixing, re-verify using “the type of caller that previously reported errors,” not just your own success.
  Validate according to the standards of whoever reported the error; this is the only way to confirm the fix is truly effective.

8 Common Pitfalls

1. Considering it fixed after browser verification: Browsers auto-complete, masking the issue.
2. Running openssl without -verify_return_error: Also auto-completes, failing to reproduce the issue.
3. Checking only CN, ignoring subjectAltName: SAN is now the standard.
4. Certificate signed for www, but request uses api: Domain mismatch.
5. Configuring cert instead of fullchain: Incomplete chain.
6. Keeping TLS 1.0/1.1 enabled: Does not meet requirements.
7. Using self-signed certificates in test environments: Mini programs do not accept them.
8. Ignoring device time: When only individual users report errors and servers are normal, suspect this first.

Real Customer Feedback (From Similar Service Reviews and Consultations on Cloud Markets)

The following excerpts are from real buyer reviews and consultations for similar operations services on Alibaba Cloud / Tencent Cloud / Huawei Cloud markets (service providers include our store and peers, provided solely for reference of real feedback, not fictional tickets from this site):

s****2 Rating: 5.0 Feb 28, 2023 11:04 Mai****8 Rating: 5.0 Jun 29, 2020 17:44 4****6 Rating: 5.0 Jan 07, 2019 14:56

a****8 Rating: 5.0 Aug 22, 2025 14:43 r****8 Rating: 5.0 May 22, 2025 15:34 t****c Rating: 5.0 Apr 18, 2025 13:58 Cai****Kang Rating: 5.0 Aug 31, 2024 12:05 2****2 Rating: 5.0 Feb 21, 2024 11:08