Proxy Status Codes

Proxy error responses identify failures that occur while processing or forwarding a request. Use the HTTP status code and the Proxy-Status response header to distinguish proxy-generated errors from responses returned by the destination server.

For SOCKS5 connections, inspect the protocol reply codes instead of HTTP status codes or headers.

Response Format

The following response fields provide status information:

For example:

HTTP/1.1 504 Gateway Timeout
Proxy-Status: mrscraper; error=connection_timeout

This response indicates that the proxy gateway could not connect to the destination website through a proxy exit IP within the allowed time.

Identifying the Response Source

HTTP/1.1 200 Connection Established

• Source: MrScraper proxy — success.
• Meaning: The HTTPS CONNECT tunnel is open. This is the proxy's confirmation, not the target website's response.

HTTP/1.1 502 Bad Gateway
Proxy-Status: mrscraper; error=connection_terminated
Content-Type: text/plain; charset=utf-8

Bad Gateway

• Source: MrScraper proxy — failure.
• Meaning: The mrscraper; error=... entry identifies a proxy-classified failure. Here, the connection closed or reset before the proxy could complete the response.

HTTP/1.1 200 OK
Content-Type: text/html

<html><body>The requested page.</body></html>

• Source: Target website — success.
• Meaning: The target returned the requested page, which the proxy relayed to the client.

HTTP/1.1 403 Forbidden
Content-Type: text/html

<html><body>Access denied by the target website.</body></html>

• Source: Target website — failure.
• Meaning: The target rejected the request. The proxy relayed its response rather than generating a proxy error.

The target-response examples show typical forwarded responses. Body content and the absence of a mrscraper error entry alone do not prove target origin: some proxy-generated failures can also lack that entry.

HTTPS CONNECT Responses

HTTPS connections through the proxy begin with a CONNECT request. Before tunnel establishment, the proxy generates the response:

A CONNECT failure does not return the destination server's application error page because the tunnel has not been established. After 200 Connection Established, the proxy cannot inspect encrypted application traffic or send a replacement HTTP error. Certificate validation failures, authentication pages, and application errors within the tunnel cannot be reported through Proxy-Status. Later transport failures close the connection instead.

destination_unavailable means no suitable proxy exit IP is available to complete your request, or the selected proxy exit IP cannot reach the destination website. It does not necessarily mean the website is down. Try again after a short delay or broaden your location targeting.

SOCKS5

If you use SOCKS5, your proxy client reports SOCKS5 reply codes instead of HTTP status codes. Check your client's error message or logs for the code, then use the tables below to find the next step.

Errors can occur when your client signs in or when it asks the proxy to connect to a website. Check which step failed: the same code can mean different things at each step.

Sign-In Responses

During sign-in, your client first agrees on an authentication method with the proxy gateway, then sends credentials if required.

SOCKS5 Connection Responses

After sign-in, your client asks the proxy to connect to the destination website. The proxy returns a code indicating whether that request was accepted or why it failed. Some clients label this code REP, which means “reply.”

Codes are shown in hexadecimal, a number format commonly used in client logs. For example, 0x04 is code 4. 0x00 means the request was accepted; other values indicate an error.

You may also see these client errors:

Retry a few times, waiting longer after each attempt. Avoid retrying requests that could cause duplicate actions. The website may have already processed the first request.

Plain HTTP Responses

For unencrypted HTTP requests, the proxy can return the following errors before sending response headers to the client. Classified failures include a mrscraper; error=... entry in Proxy-Status.

Once HTTP response headers have been sent, a later read timeout or connection termination cannot replace the response with a new 502, 504, or Proxy-Status header. The client observes a truncated response or a closed connection instead.

When to Retry

For temporary connection failures, limit the number of retries and wait progressively longer between attempts. Add a small random delay to avoid sending all retries at once.

HTTP and HTTPS CONNECT

The following guidance applies to plain HTTP responses and HTTPS CONNECT responses before the tunnel opens.

SOCKS5

Check whether the code occurred during sign-in or while connecting to the destination.

Only replay requests that are safe to repeat, such as idempotent operations or requests protected by an application-supported idempotency key. Ensure request bodies can be replayed. If the response was lost after the destination processed a request, retrying a non-idempotent operation can duplicate its effects.