Troubleshooting

Setup Checklist

Before reporting issues, please check these common setup requirements:

1. Add Your Domain to Dashboard

If you’re making requests from a web application (not localhost), you must add your domain to the proxy dashboard:

• Production domains: https://myapp.com, https://www.myapp.com
• Staging domains: https://staging.myapp.com
• Development domains: https://dev.myapp.com
• Localhost: No need to add http://localhost or http://127.0.0.1

How to add domains:

1. Log into your proxy dashboard
2. Go to “Allowed Domains” section
3. Add each domain that will make requests to the proxy
4. Save changes

2. Use the Correct URL Format

Always use the ?url= parameter format for best compatibility:

// Recommended format
'https://corsproxy.io/?url=https://example.com'

// Alternative formats (may cause issues)
'https://corsproxy.io/?https://example.com'
'https://corsproxy.io/https://example.com'

3. URL Encode Your Target URLs

Always encode URLs with special characters using encodeURIComponent():

// Properly encoded
const targetUrl = 'https://api.example.com/search?q=hello world&type=json';
const encodedUrl = encodeURIComponent(targetUrl);
const proxyUrl = `https://corsproxy.io/?url=${encodedUrl}`;

Error Response Format

Errors return JSON like this:

{
  "error": {
    "status": 400,
    "message": "No valid URL provided. Use ?url=https://example.com",
    "requestId": "uuid",
    "timestamp": 1234567890
  }
}

Common Errors

For 403s specifically, see the dedicated guide: 403 Forbidden.

401 - Invalid API Key

Message: Invalid or inactive API key. Get a valid key at https://corsproxy.io/pricing/

Solution: Verify your key value or create a new key in the dashboard.

403 - Blocked or Restricted Request

Common reasons include:

• Localhost/private IPs (e.g. 127.0.0.1, 10.x.x.x, 192.168.x.x)
• Restricted parameters (extract, input, output, ttl) on non‑Business plans
• Server‑side requests on plans that require browser-only usage

Solution: Use a public URL, remove restricted params, or upgrade your plan.

413 - Response Too Large

Message: Response exceeds <limit> size limit. Upgrade at https://corsproxy.io/pricing/

Solution: Reduce response size or upgrade your plan tier.

502 - Failed to Fetch Target

Solution: Ensure the target URL is correct and reachable.

504 - Request Timeout (30s)

Solution: The target server took too long to respond. Try again or contact the API provider.

Debugging Tips

1. Check the X-Request-ID header in responses for support requests.
2. Verify URL encoding for URLs with special characters.
3. Test the target URL directly in your browser first.
4. Check API documentation for required headers or authentication.