Client Login

Errors and Response Codes

9 min read

Use this guide to understand common proxy-related errors, response failures, timeout boundaries, and connection problems when using InstantProxies.

Not every failure means the same thing. Some errors point to authentication or allowlist issues. Others point to timeout boundaries, browser setup problems, target-site behavior, or connection-format mistakes. The fastest way to troubleshoot is to classify the failure before changing more variables.

Use this page when

Use this page when:

  • a request fails and you need to understand what kind of problem it is
  • your application returns an HTTP error, browser failure, or connection error
  • a proxy works in one environment but not another
  • you need a simpler way to separate local setup issues from destination-side issues
  • you want a quick reference before debugging a larger workflow

If the proxy is failing only in browser frameworks, continue to Browser Automation Troubleshooting.

Start with the failure boundary

An error message is useful only if you know where it surfaced.

Most proxy-related failures fall into one of these groups:

  • connection and handshake failures
  • authentication and allowlist failures
  • timeout and retry-related failures
  • destination-side errors
  • browser workflow errors
  • application-level formatting or configuration mistakes

The goal is not only to read the error. It is to identify which boundary failed first.

These terms are often used together, but they do not mean the same thing.

  • An error is the visible signal returned by the client, browser, application, or destination.
  • A failure is the point where the expected path stopped working.
  • A timeout is one specific kind of failure where a stage took too long to complete.

This matters because the same visible error can come from different failure boundaries.

For example:

  • a timeout may point to slow connection setup, slow destination response, or a weak browser wait strategy
  • a 403 may point to destination-side blocking rather than proxy authentication
  • a browser page error may happen long after the proxy path itself was already working correctly

Good troubleshooting starts by separating the visible error from the actual boundary that failed.

Common error category 1: connection failures

These usually happen before the request reaches the destination cleanly.

Examples include:

  • connection refused
  • connection reset
  • failed to connect to proxy
  • proxy connection error
  • DNS resolution failure for the proxy host
  • tunnel connection failure

These errors often point to:

  • wrong host
  • wrong port
  • wrong protocol format
  • network path issues from the runtime environment
  • local firewall or environment restrictions

Check first:

  • host is correct
  • port is correct
  • the client is using the expected proxy format
  • the runtime can reach the proxy from that environment

If basic connectivity is the main issue, continue to Connectivity Troubleshooting.

Common error category 2: authentication and allowlist failures

These happen when the proxy is reachable but access is not accepted.

Examples include:

  • proxy authentication required
  • 407 Proxy Authentication Required
  • access denied from current IP
  • allowlist or authorization failure
  • credential rejection

These errors often point to:

  • wrong username or password
  • missing credentials
  • using IP authorization from a runtime whose public IP is not authorized
  • mixing credential-based and IP-authorized setups incorrectly
  • running from a different environment than expected

Check first:

  • username and password are correct if used
  • the runtime public IP is actually allowlisted if credentials are omitted
  • the client is passing credentials in the format it expects
  • local, server, container, and CI environments are not being confused with each other

If access setup is the main issue, continue to Authentication and Allowlist Errors.

Timeouts often appear when the connection path is partially working but one stage is under pressure.

Examples include:

  • connection timed out
  • read timed out
  • request timed out
  • navigation timeout
  • script timeout
  • proxy timeout

A timeout does not always mean the same thing.

It may point to:

  • slow connection setup
  • weak timeout settings
  • repeated-run pressure
  • environment-specific instability
  • browser timing issues
  • destination-side slowness

Check first:

  • which stage timed out
  • whether the same timeout happens repeatedly at the same boundary
  • whether the issue appears only under load or repeated execution
  • whether the same path succeeds with a simpler baseline request

If timing is the main issue, continue to Timeouts, Retries, and Backoff.

Why timeout boundaries matter

A timeout is only useful if you know which stage it belongs to.

Useful timeout boundaries may include:

  • connection setup
  • proxy handshake
  • response read
  • browser navigation
  • selector or element readiness
  • repeated workflow steps

Without that boundary context, timeouts are easy to misread and easy to overcorrect.

That is why increasing timeout values blindly is often a weak first move. A timeout can be too short, but it can also be correctly exposing a deeper problem.

Common error category 4: destination-side response errors

Sometimes the proxy path is healthy, but the destination still rejects or limits the request.

Examples include:

  • 403 Forbidden
  • 429 Too Many Requests
  • CAPTCHA pages
  • rate-limited or blocked requests
  • anti-bot pages or challenge pages

These errors often point to:

  • target-site limits
  • request reputation or traffic policy issues
  • automation detection
  • destination-side throttling
  • workflows that are valid technically but restricted by the target

Check first:

  • whether the proxy path itself is healthy in a simpler validation request
  • whether the same target behavior appears across environments or frameworks
  • whether the issue is tied to one site or to all requests generally

If the destination is the likely problem, continue to Local Failures vs Target-Site Blocks and CAPTCHAs, Bans, and Destination Limits.

Common error category 5: TLS and HTTPS failures

These happen when secure connection handling is not working as expected.

Examples include:

  • SSL handshake failed
  • certificate validation error
  • TLS negotiation failure
  • secure connection failed
  • HTTPS tunnel failure

These errors often point to:

  • client TLS handling
  • certificate validation rules in the environment
  • incorrect proxy protocol assumptions
  • browser or runtime certificate handling issues
  • local runtime restrictions rather than proxy rejection alone

If secure transport is the main issue, continue to TLS, HTTPS, and Certificate Handling.

Common error category 6: browser automation errors that look like proxy errors

In browser automation, not every page failure means the proxy is broken.

Examples include:

  • page loads partially and then fails
  • browser launches but navigation breaks
  • first run works, later runs fail
  • authentication prompts or proxy dialogs appear unexpectedly
  • Selenium, Playwright, and Puppeteer behave differently from each other

These errors may actually come from:

  • browser launch configuration
  • framework-specific authentication handling
  • page timing and readiness
  • repeated-run drift
  • destination-side blocks appearing inside the browser flow

If the error appears only in Playwright, Puppeteer, or Selenium, continue to Browser Automation Troubleshooting.

Common error category 7: formatting and configuration errors

Some failures are caused by invalid proxy setup rather than transport or destination issues.

Examples include:

  • invalid proxy URL
  • unsupported proxy format
  • full proxy URL pasted into a host-only field
  • wrong scheme such as using https:// when the client expects http://
  • credentials passed in the wrong format

These usually point to:

  • incorrect connection string formatting
  • mismatched host, port, and protocol fields
  • using a format the client does not actually support

If the format is the likely problem, continue to Endpoints, Protocols, and Connection Strings.

Common HTTP response codes to interpret quickly

200-level responses

These usually mean the request succeeded at the HTTP level.

Still check whether:

  • the returned content is actually what you expected
  • the request used the intended proxy path
  • the target returned useful output instead of a challenge or degraded page

403 Forbidden

This usually means the destination rejected the request.

Common causes include:

  • target-site blocking
  • destination rules
  • anti-bot controls
  • access denied at the destination rather than at the proxy layer

407 Proxy Authentication Required

This usually means the proxy itself needs authentication and did not receive valid credentials.

Common causes include:

  • missing username and password
  • wrong credentials
  • wrong client configuration for proxy auth

429 Too Many Requests

This usually means the destination is rate limiting the workflow.

Common causes include:

  • request volume
  • repeated automation patterns
  • destination throttling
  • too much overlap or repeated execution

5xx responses

These usually mean a server-side failure somewhere in the path.

That may be:

  • destination-side instability
  • an upstream service error
  • a temporary failure that still needs classification before retrying aggressively

Do not assume every 5xx response should be retried the same way.

Fast classification checklist

When an error appears, ask these questions in order:

  1. does the same proxy work with cURL from the same environment
  2. is this a connection error, an auth error, a timeout, or a destination error
  3. does the issue happen before the request leaves the local runtime or after it reaches the destination
  4. does the issue happen in all environments or only one
  5. does the issue happen once or repeatedly in the same way
  6. is the failure appearing only inside browser automation

This helps prevent random debugging.

Common mistakes

Typical issues include:

  • treating all failures as generic network problems
  • retrying before the failure category is understood
  • assuming a browser page error proves the proxy is broken
  • debugging the full workflow before validating a minimal request
  • ignoring environment differences when interpreting the same error
  • focusing on the final visible error instead of the first failing boundary

These patterns make errors harder to interpret and slower to fix.

Use this sequence:

  1. reproduce the error with the smallest meaningful request path
  2. verify the same proxy with cURL from the same environment
  3. classify the failure category
  4. compare environments if the result differs across runtimes
  5. move into framework-specific or destination-specific troubleshooting only after the boundary is clearer

Key points

  • the same visible failure can come from very different boundaries
  • the most useful first step is to classify the error before changing more variables
  • 407 usually points to proxy authentication problems
  • 403 and 429 often point to destination-side rejection or limits
  • timeouts are only useful when you know which stage is timing out
  • browser automation adds its own failure boundaries on top of the proxy path

Next step

If the problem is still unclear at the connection level, continue to Connectivity Troubleshooting.

If the main issue is access rejection, continue to Authentication and Allowlist Errors.