Troubleshooting
Use this page when a NinjaProxy request is failing and you need the fastest path to the likely cause. Start with the exact endpoint shown in your portal, then work outward from auth, protocol, proxy type, and account limits.
Do not guess endpoints: host and port values are account-specific. Copy the exact HTTP or SOCKS5 endpoint from the portal instead of inventing hostnames, alternate ports, or undocumented gateway variants.
Fast triage checklist
- Copy the exact endpoint from the portal again.
- Confirm whether you are using an assigned/static endpoint or a rotating gateway endpoint.
- Verify the auth method: username + API key, or IP whitelist.
- Confirm the protocol your client expects: HTTP or SOCKS5.
- Check your current balance and connection allowance before scaling retries.
Common failures
| Symptom | Likely cause | Fix |
|---|---|---|
407 Proxy Authentication Required | Malformed credentials, wrong API key, or missing URL encoding for special characters. | Re-copy your username and API key, keep username controls in the username field, and percent-encode characters like @, :, and / before embedding them in a proxy URL. |
| Connection timeout | Endpoint was typed manually, protocol does not match the client, or you saturated available connections. | Copy the endpoint from the portal again, verify HTTP vs SOCKS5, reuse connections, and reduce client concurrency if you are near your plan limit. |
| Same IP on every request | You are using an assigned/static endpoint, or you are reusing the same rotating session token. | For fresh routes, use a rotating gateway endpoint. If you already are, remove or change the --session-... token so the gateway can choose a different route. |
| CAPTCHA or block responses | Proxy type does not match target sensitivity, or you are hitting the target too hard from one route. | Move sensitive scraping and browser automation to residential or mobile traffic, rotate routes deliberately, and lower burstiness so one IP or session does not absorb all requests. |
| Requests fail despite correct credentials | Balance is exhausted, the account hit a connection limit, or the target is rejecting the route after proxy auth succeeds. | Check for 402 Payment Required, review your plan's concurrent connection allowance, and test the same request through a better-fit proxy type if the target is blocking the current one. |
| Whitelist mode not working | Your real egress IP does not match the allowlisted IP or CIDR, even if the server itself looks correct. | Confirm the public egress IP that reaches NinjaProxy, update the whitelist entry if it changed, and remember that whitelist auth depends on the source IP the gateway sees. |
| SOCKS5 vs HTTP mismatch | The client is speaking the wrong protocol for the endpoint, or that proxy family only exposes HTTP for your account. | Use the exact protocol and endpoint shown in the portal. Assigned datacenter endpoints can expose HTTP and SOCKS5 when available; residential and mobile docs currently use assigned HTTP endpoints; rotating accounts can have HTTP or SOCKS5 gateway endpoints. |
| Special-character URL encoding issues | The username or API key contains reserved URL characters and the proxy URL was pasted raw. | Encode credential values before building the proxy URL, or pass username/password in separate client fields when your library supports that pattern. |
| Balance, plan, or concurrency limit issues | New proxy requests are being rejected because prepaid balance is empty or too many TCP connections are already open. | Top up balance for usage-billed traffic, enable auto top-up if needed, and cap worker concurrency below your plan ceiling so retries still have headroom. |
Special-character encoding example
If you embed credentials in a proxy URL, encode the credential values first rather than pasting raw secrets into the URL.
import urllib.parse
username = "myuser"
api_key = "p@ss:word/123"
endpoint = "<HTTP_ENDPOINT>" # Copy from the portal
proxy_url = f"http://{username}:{urllib.parse.quote(api_key, safe='')}@{endpoint}"
print(proxy_url)Which doc to open next
- Authentication — username + API key, whitelist mode, and auth error fixes.
- Rate Limits — connection pooling, balance exhaustion, and concurrency ceilings.
- Python integration — requests, httpx, aiohttp, Scrapy, and Playwright examples.
- Node.js integration — fetch, axios, and Playwright examples.
- Datacenter proxies, Residential proxies, Mobile proxies, and Rotating proxies — product-specific endpoint behavior and protocol support.