Proxy errors troubleshooting - Bright Data Docs

This article addresses all proxy errors originating from BrightData. While using our proxies, you may encounter errors that do not originate from Brightdata. To identify the source of the error, check if the response headers include BrightData error fields (seen below). Ensure you receive all response headers by following the instructions as seen below (-v flag).
If the error response lacks BrightData error header fields, the issue is unrelated to BrightData and instead you should refer to How to overcome website blocking.

Bright Data HTTP Errors

HTTP Header Fields

The following fields are returned upon and HTTP or HTTPS requests:

Field	Description	Examples	REST API Field Name
`HTTP Error`	The protocol error numbers	`404` or `502`	status_code
`x-brd-err-code`	Bright data module and error code number	`client_10001`	error_code
`x-brd-error`	Bright data main error message	Authentication failed	error
`x-brd-err-msg`	Bright data elaborated message and actions	Authentication failed. Check your credentials or your account status in https://brightdata.com/cp/settings/billing	error_message

Getting HTTP header fields

Testing from command line

To view and test your settings, or restoring an issue, you can run a curl command from your shell prompt and add the option flag -v or i. These flags will run curl in verbose mode and print out the header fields, including the custom error code and message.

curl -v [rest of curl command options]

To see a more compact view with the header fields response only use the -i option for curl:

curl -i [rest of curl command options]

Alternatively, you can use the nc command to get the fields printed to screen:

echo "[tcp nc inputs]" | nc -C -v brd.superproxy.io 33335

nc inputs may include “empty” lines, those are essential for correct testing using nc command

`curl` Command snippet

curl command snippet, with all required zone parameters is available in the Overview tab in Bright Data control panel for the zone you are working on.

Accessing via programming language

Bright Data HTTP header fields can be accessed thru your programming language, as any other HTTP header field.

Accessing via Bright Data’s Proxy REST API

Bright data offers a REST API to access its proxy networks as well as the Unlocker product and our SERP for targeting search engines. The error field names are slightly different , yet the content is identical.

Example response:

"status_code": 407,
"status_message": "Proxy Authentication Required",
"error": "Proxy Authentication Required",
"error_message": "No proxy credentials provided. Please add credentials and try again.",
"error_code": "client_10010"

Error Catalog

HTTP Error 400

When Using the Data center/ISP or gIPs products with the -ip-x.x.x.x targeting flag, the error code 400 can appear in case the IPs under your zone has been refreshed, removed, or simply changed due to system updates

This error typically arises after your BrightData account has been recently suspended. An automatic suspension occurs if your account balance becomes negative. If the suspension extends beyond 24 hours, the static allocated IPs will be released from your account. Upon reactivation, the reallocated IPs may differ from the original ones, thus if the previously allocated IPs are still being targeted - this error is thrown.

Whenever this error appears, you should go to your Bright Data Zones page, and view the updated list of IPs relevant to this zone.

x-brd-error	Proxy Error: ip_requested_not_allocated_by_customer
x-brd-err-msg	Requested IP `##.##.##.##` is not allocated to this zone. Select an IP that is allocated to this zone or skip the -ip parameter in proxy username

x-brd-error	Peer not found
x-brd-err-msg	No proxy found in selected default countries: %Countries_list%. Please revise your default country selection or use `-country` flag to another country and override default settings. Read more here: https://docs.brightdata.com/api-reference/proxy/geolocation-targeting

x-brd-error	Peer not found
x-brd-err-msg	No super proxy found in selected country %COUNTRY_CODE%. Please try another another country or omit the -country flag completely if applicable. Read more here: https://docs.brightdata.com/api-reference/proxy/select\_super\_proxy\_in\_specific\_country

HTTP Error 401

These are the x-brd-err-code values for HTTP error 401:

x-brd-error	Auth failed: IP blacklisted [IP]
x-brd-err-msg	Auth Failed IP blacklisted: [IP]. Check FAQ: how to blacklist/whitelist ips and domains? to resolve

HTTP Error 402

These are the x-brd-err-code values for HTTP error 402:

x-brd-error	Residential Failed `bad_endpoint`
x-brd-err-msg	Residential Failed (`bad_endpoint`) - Requested site is not available for immediate residential (no KYC) access mode due to the fact that `%HTTP_METHOD%` requests are not allowed. To get full residential access for targeting this site, Fill in the KYC form: https://brightdata.com/cp/kyc

x-brd-error	Residential Failed `bad_endpoint`
x-brd-err-msg	Residential Failed (`bad_endpoint`) - Requested site is not available for immediate residential (no KYC) access mode in accordance with robots.txt. To get full residential access for targeting this site, Fill in the KYC form: https://brightdata.com/cp/kyc

HTTP Error 403

These are the x-brd-err-code values for HTTP error 403:

x-brd-error	No Protocol
x-brd-err-msg	Protocol was missing from original request. Please add either HTTP or HTTPS and retry.

x-brd-error	No Destination Host
x-brd-err-msg	No destination host. Destination host is missing or incorrect. Check your request parameters and try again

x-brd-error	You are trying to use Scraping Browser zone as regular proxy
x-brd-err-msg	You are trying to use Scraping Browser zone as regular proxy. A browser should be used to access this zone. See Scraping Browser for information on how to access your scraping browser zone

x-brd-error	Forbidden: this super proxy is allowed to be used only for China domains via China peers. Otherwise use brd.superproxy.io. For more details review the following: https://docs.brightdata.com/proxy-networks/mobile/faqs#how-to-browse-chinese-sites-by-using-chinese-residentials-ips
x-brd-err-msg	Forbidden: this super proxy is allowed to be used only for China domains via China peers. Otherwise use brd.superproxy.io. For more details review the following: https://docs.brightdata.com/proxy-networks/mobile/faqs#how-to-browse-chinese-sites-by-using-chinese-residentials-ips

x-brd-error	Bad protocol
x-brd-err-msg	The protocol you are using to access our proxy is not supported. Bright data supports HTTP, HTTPS & SOCKS5 upon special approval. Please fix your protocol and try again

x-brd-error	Bad port
x-brd-err-msg	Bad Port used. Ports we support: https://docs.brightdata.com/proxy-networks/faqs#how-to-see-supported-ports-and-protocols

x-brd-error	Forbidden: target site requires special permission. Contact BrightData for assistance
x-brd-err-msg	Forbidden: target site requires special permission. You are trying to access a target site which is not permitted by our compliance policy. In order to gain access you may need to undergo a KYC process, you can do so by filling in the form: https://brightdata.com/cp/kyc If you have already completed the KYC approval, please contact your account manager for further details.

x-brd-error	Forbidden: target site requires special permission. Contact BrightData for assistance
x-brd-err-msg	Forbidden: target site requires is a government site and requires special permissions to access. In order to gain access you may need to undergo a KYC process, you can do so by filling in the form: https://brightdata.com/cp/kyc If you have already completed the KYC approval, please contact your account manager for further details.

x-brd-error	Forbidden: request needs to be made using residential network
x-brd-err-msg	Forbidden: You are accessing a domain which is not permitted to access by Bright Data Datacenter or ISP networks. Please retry your request using a Residential network zone.

x-brd-error	Forbidden: requests to this domain are blocked using the proxy networks, please get access via a Web unlocker zone or IDE tools, or contact your account manager to assist
x-brd-err-msg	Forbidden: requests to this domain are blocked using the Datacenter, ISP and Residential proxy networks, please get access via a Web unlocker zone or IDE tools, or contact your account manager for further assistance

x-brd-error	Forbidden: target blocked
x-brd-err-msg	Forbidden: You tried to target www.somehost.com but got blocked. It can be related to your blacklist or whitelist settings or the target site is not allowed by Bright Data policy. Read more: https://docs.brightdata.com/proxy-networks/faqs#what-is-error-code-403

x-brd-error	Access denied: <URL> is classified as <category> and blocked by Bright Data
x-brd-err-msg	Access denied: `%URL%` is classified as `%CATEGORY%` and blocked by Bright Data as it might breach Bright Data usage policy. For more details review the following: https://docs.brightdata.com/proxy-networks/residential/network-access#residential-proxy-network-policy

x-brd-error	Country %COUNTRY% is not permitted for targeting, please modify to a different country
x-brd-err-msg	Country %COUNTRY% is not permitted for targeting, please modify to a different country

x-brd-error	Forbidden: Target %HOST% is blocked.
x-brd-err-msg	Forbidden: target %HOST% is blocked by Bright Data. Target host provides web service or information of Bright Data and our proxies cannot be used to target it. For further assistance please contact support@brightdata.com

x-brd-error	Forbidden host
x-brd-err-msg	Destination host is blocked either by Brightdata in accordance with our compliance policy or by your account rules’ configuration. Please check if this domain is allowed for targeting by this zone in the zone settings: https://brightdata.com/cp/zones/%ZONE\_NAME%/access\_params?id=%ACC\_ID%

x-brd-error	Proxy port %PORT% is restricted. Contact Bright Data support
x-brd-err-msg	Proxy port %PORT% is restricted. Contact Bright Data support

x-brd-error	Forbidden SERP domain
x-brd-err-msg	Destination host is blocked either by Brightdata in accordance with our compliance policy or by your account rules’ configuration. Please check if this domain is allowed for targeting by this zone in the zone settings: https://brightdata.com/cp/zones/%ZONE\_NAME%/access\_params?id=%ACC\_ID%

HTTP Error 407

If you get HTTP error 407, this implies there is an error in authentication. This can be due to incorrect credentials or due to your account being suspended.

x-brd-error	Authentication failed
x-brd-err-msg	Invalid authentication: check credentials and retry. Bright Data credentials include your account ID, zone name and password

x-brd-error	Invalid Auth
x-brd-err-msg	Invalid authentication: check credentials and retry

x-brd-error	Auth failed: Zone not found.
x-brd-err-msg	Authentication failed: zone not found. Zone name used is either misspelled, or zone is disabled or deleted. Check your inputs, and validate zone is “Active” in Bright Data control panel, or use our API to get current zone status: Get Active Zones

x-brd-error	Proxy Authentication Required
x-brd-err-msg	No proxy credentials provided. Please add credentials and try again.

x-brd-error	Account is suspended. Login to activate your account
x-brd-err-msg	Account is suspended. Login to activate your account

x-brd-error	Authentication failed
x-brd-err-msg	You are not allowed to access our API via this IP. Please verify your settings or whitelist this IP.

x-brd-error	KYC Required. Please visit http://brighdata.com/cp/kyc and ensure you are verified
x-brd-err-msg	KYC Required. Please visit http://brighdata.com/cp/kyc and ensure you are verified

x-brd-error	IP parameter <IP> is incorrect, use correct format in the IP parameter
x-brd-err-msg	IP parameter <IP> is incorrect, use x-luminati-ip header format in the IP parameter

HTTP Error 429

These are the x-brd-err-code values for HTTP error 429:

x-brd-error	Your limited trial mode account exceeded the allowed rate limits. Add payment method to receive $5 credit and remove rate limits. You will not be charged
x-brd-err-msg	Your limited trial mode account exceeded the allowed rate limits. Add payment method to receive $5 credit and remove rate limits. You will not be charged

x-brd-error	Requests rate to `%URL%` is too high
x-brd-err-msg	Rate limit for domain `%DOMAIN%` has been reached. Bright Data’s health monitor is throttling down these requests to prevent overloading of the target website. Reduce requests rate and try again or contact Brightdata.com for support

x-brd-error	Requests rate to `%URL%` is too high
x-brd-err-msg	Rate limit for domain `%DOMAIN%` has been reached. Bright Data’s health monitor is throttling down these requests to prevent overloading of the target website. Reduce requests rate and try again or contact Brightdata.com for support

HTTP Error 502

These are the x-brd-err-code values for HTTP error 502:

x-brd-error	Block direct route
x-brd-err-msg	Request reroute blocked. You chose option not to reroute requests thru our superproxy on failure so reroute was blocked. To see more about this setting see: Request Error Handling

x-brd-error	Proxy Error: We do not have proxies in the city you requested
x-brd-err-msg	Proxy Error: We do not have proxies in the city you requested, please check the spelling or try again later. Check Target a specific city for proper use of city targeting.

x-brd-error	Host is blocked in requested country
x-brd-err-msg	Host you are trying to access is blocked in requested country. Please change country and retry.

x-brd-error	Could not resolve host `%HOST%`
x-brd-err-msg	Could not resolve host `%HOST%`. Check host name is correctly spelled and retry. If host is properly spelled contact brightdata.com for DNS support.

x-brd-error	Zone has reached usage limit
x-brd-err-msg	Zone has reached usage limit. Go to https://brightdata.com/cp/zones to remove/modify limitation.

​Bright Data HTTP Errors

​HTTP Header Fields

​Getting HTTP header fields

​Testing from command line

​curl Command snippet

​Accessing via programming language

​Accessing via Bright Data’s Proxy REST API

​Error Catalog

​HTTP Error 400

​HTTP Error 401

​HTTP Error 402

​HTTP Error 403

​HTTP Error 407

​HTTP Error 429

​HTTP Error 502