Skip to main content
This article provides information on how to identify proxy errors from other errors, how to analyze errors, troubleshoot and resolve issues with Bright Data proxy services.

​
How can I tell if the error I got is originates from a Bright Data proxy?

While using our proxies, you may encounter errors that do not originate from Bright Data. To identify the source of the error, check if the response headers include BrightData error fields listed below, we cover most errors by proxy layer in those codes. If you are still not able to get to your target website, or receive a response HTTP status 200 without the data you are expecting, you were probably blocked. In this article: Overcoming website blocking we provide some best practices.

​
Bright Data Proxy Errors Troubleshooting

​
Bright Data’s proxy error format and standard now supports RFC9209

Starting October 2025, Bright Data supports two sets of headers to relay proxy error in response payload:
  1. Propietary x-brd-* fields: x-brd-err-code and x-brd-err-msg
  2. Standard RFC9209Proxy-Status response header supporting RFC9209 standard proxy error format.
The Proxy-Status header standard field will eventually replace the x-brd-* fields, during 2026.

​
What is RFC9209?

RFC9209 is the standard on how to relay proxy errors in response headers over proxy. Bright Data is adopting this standard and applied it to all its error catalog. This will allow customers’ code as well as 3rd party tools using proxy as infrastructure to refer to error from proxy interaction and resolve issues faster. You can read more about it here: The Proxy-Status HTTP Response Header

​
How to implelement RFC9209?

​
Example Proxy-Status HTTP header

Proxy-Status: brd.brighdata.io; 
received-status=400; 
error=destination_ip_unroutable; 
details="client-10060: 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."

​
Implementation Instructions

  1. Parse the response header: Ensure that your systems are configured to interpret the Proxy-Status header in HTTP responses.
  2. Extract relevant fields:
   - received-status: Provides the HTTP status code received.    - error: Describes the general error encountered.    - details: Contains specific error codes and further information from our error catalog.    - The first field in the details will be bright data error code (like: client_10060) followed by ’:’ (colon) delimiter.     - You can browse directly to the error document using this prefix, and replacing the ’_’ (underscore) with ’-’ (dash) in the error code: https://docs.brightdata.com/proxy-networks/errorCatalog#[Bright data error code]. Example for client_10060: https://docs.brightdata.com/proxy-networks/errorCatalog#client-10060
  1. Adapt your error handling processes according to these structured codes to improve debugging and ensure a seamless proxy operation.

​
Bright Data HTTP proxy header fields

The following fields are returned upon and HTTP or HTTPS requests:
FieldDescriptionExamplesREST API Field Name
HTTP ErrorThe protocol error numbers404 or 502status_code
x-brd-err-codeBright data module and error code numberclient_10001error_code
x-brd-errorBright data main error messageAuthentication failederror
x-brd-err-msgBright data elaborated message and actionsAuthentication failed. Please check your credentials or review your account status and billing settings.error_message
Proxy-StatusRFC9209 compliant response header. It will include Bright Data proxy server, the HTTP status and details string which has a reference to Bright Data’s error code.Proxy-Status: brd.superproxy.io; received-status=407; error="http_request_denied"; details="client_10000: Invalid authentication: check credentials and retry. Bright Data credentials include your account ID, zone name and password"Not supported

​
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 API 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: Your [proxy type] [DC|ISP] zone does not have IPs in selected countries. Either IPs location has changed, or zone not configured with proxies in selected countries. Check zone configuration and try again with relevant country code. Read more: https://docs.brightdata.com/api-reference/proxy/geolocation-targeting

​
HTTP Error 401

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

​
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

​
HTTP Error 403

HTTP 403 response code means you are forbidden from accessing a valid URL. The server processed the request, but it can’t fulfill the request either due to the way the request was sent by the client or due to Bright Data policy, blocking target access. 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 Browser API zone as regular proxy
  • x-brd-err-msg: You are trying to use Browser API zone as regular proxy. A browser should be used to access this zone. See Browser API for information on how to access your Browser API zone
  • x-brd-error: Forbidden: You tried to target %HOST% but got blocked
  • x-brd-err-msg: Forbidden: You tried to target %HOST% but got blocked since this host is not an allowed target in your zone’s allowlist security setting. Please add this host to your allowlist or delete all content from allowlist to allow all targets.
  • x-brd-error: Forbidden: You tried to target %HOST% but got blocked
  • x-brd-err-msg: Forbidden: You tried to target %HOST% but got blocked since this host is explicitly blocked target in your zone’s denylist security setting. Please remove this host from your denylist or delete all content from denylist to allow all targets.
  • 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: 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 an Unlocker API 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 an Unlocker API zone or IDE tools, or contact your account manager for further assistance
  • x-brd-error: Forbidden: Target $host is blocked by Bright Data on IPv6 protocol. Please try IPv4 proxies or our Unlocker API to access this target.
  • x-brd-err-msg: Forbidden: Target $host is blocked by Bright Data on IPv6 protocol. Please try IPv4 proxies or our Unlocker API to access this target.
  • 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: You tried to target %HOST% but got blocked.
  • x-brd-err-msg: Forbidden: You tried to target %HOST% but got blocked by Bright Data policy settings. Either this website is forbidden by Bright Data policy or your account doesn’t have the right permission to access it.
  • x-brd-error: Forbidden: You tried to target %HOST% but got blocked.
  • x-brd-err-msg: Forbidden: You tried to target %HOST% but got blocked by Bright Data policy settings. Either this website is forbidden by Bright Data policy or your account doesn’t have the right permission to access it.
  • x-brd-error: Forbidden: You tried to target %HOST% but got blocked.
  • x-brd-err-msg: Forbidden: You tried to target %HOST% but got blocked by Bright Data policy settings. Either this website is forbidden by Bright Data policy or your account doesn’t have the right permission to access it.
  • x-brd-error: Forbidden: You tried to target %HOST% but got blocked.
  • x-brd-err-msg: Forbidden: You tried to target %HOST% but got blocked by Bright Data policy settings. Either this website is forbidden by Bright Data policy or your account doesn’t have the right permission to access it.
  • 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/
  • x-brd-error: Forbidden SERP domain
  • x-brd-err-msg: Destination host is blocked either by Bright Data 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/

​
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 allowlist this IP.
  • 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: Requests rate from account is too high
  • x-brd-err-msg: Your limited trial mode account exceeded the allowed rate limits. Reduce requests rate and try again or complete the [verification process] to remove rate limits. You will not be charged for this request.
  • 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
  • x-brd-error: Requests rate per IP is too high
  • x-brd-err-msg: Rate limit per IP %IP% on zone %ZONE% has been reached. Requests are throttled down to avoid overload. Either increase number of IPs or reduce rate, and review your rotation logic or your response size for unexpected increase to assure even distribution of requests and bandwidth across IPs of this zone.

​
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: 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.
  • 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: No IPv6 address (AAAA record) found for %HOST%
  • x-brd-err-msg: Attempting to resolve %HOST% to IPv6 failed. This is probably because the host you are targeting does not publish an IPv6 IP address. Retry the request on an IPv4 proxy.
⌘I