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}`;

// ❌ Not encoded (may break)
const proxyUrl = `https://corsproxy.io/?url=https://api.example.com/search?q=hello world&type=json`;

Common Error Responses

400 - No URL Provided

{
  "error": {
    "status": 400,
    "message": "No URL provided",
    "usage": "Append ?url=https://example.com to the proxy URL"
  }
}

Solution: Make sure you’re including a target URL in your request.

403 - Cannot Proxy to Localhost

{
  "error": {
    "status": 403,
    "message": "Cannot proxy to localhost",
    "details": {
      "suggestion": "This proxy runs on Cloudflare's edge network and cannot access your local machine."
    }
  }
}

Solution: Use a public URL instead of localhost. For local development, run a local CORS proxy.

502 - Failed to Fetch Target URL

{
  "error": {
    "status": 502,
    "message": "Failed to fetch target URL",
    "details": {
      "targetUrl": "https://invalid-domain.com",
      "error": "DNS resolution failed"
    }
  }
}

Solution: Check that the target URL is correct and accessible.

504 - Request Timeout

{
  "error": {
    "status": 504,
    "message": "Request timeout",
    "details": {
      "timeout": 30000
    }
  }
}

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