Understanding and resolving failed proxy requests is crucial to maintaining reliable infrastructure. We provide a powerful Live Log Viewer combined with traceable request identifiers to help you debug issues efficiently and in real time.

Identifying Failed Requests

Every authenticated request that passes through our network includes a special response header:

x-byteful-request-id: 90c1d76f-4551-4d15-9087-b37421d6b7c7

This x-byteful-request-id is a unique identifier tied to that request’s Log ID in the Live Network Activity Viewer. You can use this ID to locate and inspect the exact request, its metadata, and its outcome.

Debugging with cURL

You can inspect your proxy request headers and outcomes using the curl CLI. Below is an example of a successful proxy tunnel request, which returns an x-byteful-request-id header:

curl --proxy 124.103.51.11:8000 --proxy-user example_user:example_pass --verbose https://ipinfo.io

Example output (truncated for readability):

> CONNECT ipinfo.io:443 HTTP/1.1
> Proxy-Authorization: Basic ZXhhbXBsZV91c2VyOmV4YW1wbGVfcGFzcw==
< HTTP/1.1 200 OK
< x-byteful-request-id: 90c1d76f-4551-4d15-9087-b37421d6b7c7
< x-byteful-status-code: 200
< x-byteful-warp-enabled: true
...

You can now go to the Live Activity section in your dashboard, locate the Log ID 90c1d76f-4551-4d15-9087-b37421d6b7c7, and inspect:

Network used
Proxy IP address
Target domain
Duration and bytes
Internal error code (if failed)

Headers

All responses from Byteful will contain the following headers:

Header	Type	Meaning
`x-byteful-request-id`	`UUIDv4`	The unique ID of the request for cross-referencing in the dashboard.
`x-byteful-status-code`	`u16`	The Byteful code (error or success) associated with this request.
`x-byteful-warp-enabled`	`bool`	Wether or not your request was sped up using our WARP pathing technology.

Common Codes and Troubleshooting

We do not expose HTTP status codes due to TLS encryption. Instead, errors are represented by 4 digit internal codes shown in the Live Network Activity Viewer. The last digit of this internal code code is used to aid debugging by our support team and is not necessary for the customer to understand. As such, we display the last digit as x in this table.

Byteful Customer Error Reference

Dashboard Code	HTTP Code	Message
200	`200`	Success
301	`301`	Redirecting to different target
100x to 200x	`500`	Server encountered an error while proxying your request. Please contact [email protected] if this error persists.
201x to 203x	`407`	Invalid proxy credentials. Please check your username and password and try again.
206x	`400`	Invalid username parameters provided. Please check your proxy username format and try again.
207x	`500`	Server encountered an error while proxying your request. Please contact [email protected] if this error persists.
208x	`407`	Invalid proxy credentials. Please check your username and password and try again.
301	`500`	Redirecting to different target.
310x to 312x	`502`	Failed to reach target. Please try again or contact [email protected] if this error persists.
314x	`500`	Server encountered an error while proxying your request. Please contact [email protected] if this error persists.
315x	`400`	The target hostname provided is invalid. Please check the target URL and try again.
316x to 317x	`403`	You are accessing a restricted target. Please contact [email protected] if you believe this is incorrect.
410x	`500`	Connection terminated by Byteful.
411x to 412x	`403`	Exceeded maximum allowed connection duration. Please try again or contact [email protected] if this error persists.
420x	`429`	Exceeded maximum allowed rate of requests. Please reduce your request rate and try again.
421x	`429`	Concurrency limit exceeded. Please contact [email protected] if this error persists.
422x	`429`	Bandwidth limit exceeded. Please contact [email protected] if this error persists.
423x	`403`	Target website is blacklisted. Please contact [email protected] if this error persists.
450x	`500`	Server encountered an error while proxying your request. Please contact [email protected] if this error persists.
451x	`503`	No node found for given parameters. Please check your proxy username format and try again.
452x	`500`	Server encountered an error while proxying your request. Please contact [email protected] if this error persists.
500x	`500`	Server failed to process request. Please try again or contact [email protected] if this error persists.
501x to 502x	`500`	Server encountered an error while proxying your request. Please contact [email protected] if this error persists.
800x to 810x	`500`	Network communication error. Please try again or contact [email protected] if this error persists.
820x	`502`	Failed to reach target. Please try again or contact [email protected] if this error persists.
821x	`503`	No node found for given parameters. Please check your proxy username format and try again.
822x	`502`	The target refused the connection. Please verify the target host and port are correct and accepting connections.
823x	`502`	The target’s network is unreachable. Please check the target address and try again.
824x	`502`	The target host is unreachable. Please check the target address and try again.
900x to 901x	`500`	Server encountered an error while proxying your request. Please contact [email protected] if this error persists.
902x	`405`	Unsupported protocol method. Please contact [email protected] if this error persists.
910x	`400`	Error processing your request. Please check your request and try again.
999x	`500`	Server failed to process request. Please try again or contact [email protected] if this error persists.

Suggested Fixes

Authentication Errors (201x to 203x): Verify your proxy username and password. Double-check authentication format.
Data or Connection Limits (421x or 423x): Upgrade your plan or reduce simultaneous requests.
Target Restricted (423x): The target website or port may be blocked by your plan or region. Try a different network or contact support.

Still Need Help?

If you cannot resolve the issue using the Log ID and error code, please reach out to our support team with:

The full x-byteful-request-id (If within 7 days of the issue and request)
Target domain
Approximate timestamp
Proxy credentials used (if applicable)

📩 [email protected]

Getting Started

Documentation

Trust & Safety

Policies

Debugging Proxy Errors

Identifying Failed Requests

Debugging with cURL

Headers

Common Codes and Troubleshooting

Byteful Customer Error Reference

Suggested Fixes

Still Need Help?

​Identifying Failed Requests

​Debugging with cURL

​Headers

​Common Codes and Troubleshooting

​Byteful Customer Error Reference

​Suggested Fixes

​Still Need Help?

Identifying Failed Requests

Debugging with cURL

Headers

Common Codes and Troubleshooting

Byteful Customer Error Reference

Suggested Fixes

Still Need Help?