Connection troubleshooting

Connection errors when calling the API (such as Failed to establish a new connection, getaddrinfo failed, timeouts or SSL errors) usually come from your machine’s network, DNS or proxy software. Work through these steps in order.

1. Try the other endpoint

YesCaptcha has two endpoints: https://api.yescaptcha.com (global) and https://cn.yescaptcha.com (China). Use the China endpoint on servers in mainland China and the global one elsewhere. If you switch, query results on the same endpoint too.

curl -s https://api.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'
curl -s https://cn.yescaptcha.com/getBalance -H 'Content-Type: application/json' -d '{"clientKey": "YOUR_CLIENT_KEY"}'

If either returns JSON, your network works and the problem is the route to the other endpoint.

2. Check proxy software

You don’t need a proxy to reach YesCaptcha. If proxy or VPN software is running:

• Turn it off and try again;
• If you must keep it on, use rule-based (PAC) mode instead of global mode, or add api.yescaptcha.com and cn.yescaptcha.com to the direct list;
• SSLEOFError(8, 'EOF occurred in violation of protocol') in Python with a proxy running is usually caused by the proxy too; turn it off or let these domains connect directly.

3. Check the network and DNS

ping api.yescaptcha.com

• “Unknown host”: DNS resolution failed. Flush the DNS cache (Windows: ipconfig /flushdns; macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder), or switch your DNS to a public resolver (such as 8.8.8.8, 223.5.5.5 or 119.29.29.29) and try again.
• Ping fails but the name resolves: the network may block ICMP, which doesn’t mean the API is unreachable. Trust the curl result from step 1.

4. SSL certificate errors

• Certificate has expired or certificate verify failed: first check that your system clock is correct, then update your OS, Python’s certifi, Postman or other tools so they have current root certificates.
• Always use https://. Don’t switch to http:// or turn off certificate checks to get around errors.

5. Still stuck?

Contact support with the full error message, the endpoint you use, where your server is, and the curl output from step 1.