Proxy Client Errors

This document lists all errors that the proxy can return, along with their HTTP status codes and descriptions.

Error Categories

1. Authentication Errors (HTTP 407)

Status: 407 Proxy Authentication Required

These errors occur when your credentials (username/password) are incorrect or your username string is malformed.

Basic Authentication

Error Code	Status	Message	Description
wrong_customer_credentials	407	Auth Failed	Invalid username or password provided.
bad_basic_auth_format	407	Bad Auth Format	Basic authentication header has incorrect format.
ip_whitelisted_bad_port	407	Auth Failed	IP is whitelisted but wrong port was used.

Attribute Parsing

Error Code	Status	Message	Description	More Info
bad_attributes_user_missing	407	Proxy Auth Required	’user’ attribute missing.	user_xxxx is missing from username.
bad_attributes_type_missing	407	Proxy Auth Required	’type’ attribute missing.	type_mobile, type_residential, etc. missing.
bad_attributes_parse_error	407	Proxy Auth Required	Failed to parse attributes.	Check comma separation.
bad_attributes_session_name_too_long	407	Bad Authentication	Session name > 32 chars.	Must be 1-32 characters.
bad_attributes_session_name_invalid_character	407	Bad Authentication	Invalid chars in session name.	Use a-Z and 0-9 only.
region_country_is_missing	407	Proxy Auth Required	Region specified without country.	Used region_xxx without country_xx.
city_country_is_missing	407	Proxy Auth Required	City specified without country.	Used city_xxx without country_xx.
city_region_is_missing	407	Proxy Auth Required	City specified without region.	Used city_xxx without region_xx.
bad_os	407	Proxy Auth Required	Invalid operating system.	Wrong os_xx flag.

Feature/Session Errors

Error Code	Status	Message	Description	More Info
invalid_country_specified	407	Proxy Auth Required	Invalid country code.	E.g., country_US3.
multi_attr_is_not_supported	407	Proxy Auth Required	Multiple attributes not supported.

2. Bad Request Errors (HTTP 400)

Status: 400 Bad Request

The request is malformed or contains invalid parameters.

Request Validation

Error Code	Status	Message	Description
host_not_supported	400	Bad Host	Target host is not allowed or invalid.
port_not_supported	400	Bad Port	Target port is not allowed or invalid.
host_not_found	400	Bad Request	Target host could not be found.
bad_asn	400	Bad Request	Invalid ASN specified.
header_base64_validate_error	400	Bad Request	Base64 validation failed for header.
header_parse_error	400	Bad Request	Failed to parse request headers.
header_base64_decode_error	400	Bad Request	Base64 decoding failed for header.

Feature Configuration

Error Code	Status	Message	Description	More Info
bad_coordinates	400	Bad Request	Invalid lat/lon coordinates.
bad_session_duration_format	400	Bad Request	Invalid duration format.	sesstime_10min is invalid (numbers only).
bad_auto_renew_value	400	Bad Request	Auto-renew must be boolean.	sessreplace_true or sessreplace_false.
session_too_long	400	Bad Request	Duration > 10080 mins.	Max 1 week.
session_too_short	400	Bad Request	Duration < 1 min.	Min 1 minute.
incorrect_session_ip_collision_value	400	Bad Request	Invalid IP collision value.	Must be strict or flexible.
incorrect_session_asn_value	400	Bad Request	Invalid ASN value.	Must be strict or flexible.
incorrect_pool	400	Bad Request	Invalid pool specified.	Check pool_xxx options.
bad_region_name	400	Bad Request	Invalid region name.
bad_city_name	400	Bad Request	Invalid city name.
country_not_available	400	Bad Request	Country not available.	country_xxx unavailable.
feature_not_supported	400	Bad Request	Feature not supported.	Only standard flags supported.
bad_type	400	Bad Request	Invalid network type.	mobile, residential, residentialonly.

3. Forbidden Errors (HTTP 403)

Error Code	Status	Message	Description
host_not_allowed	403	Bad Host	Target host is forbidden/not allowed.

4. Conflict Errors (HTTP 409)

Error Code	Status	Message	Description	More Info
session_asn_ip_exhausted_for_user	409	Conflict	No more IPs for ASN session.	Occurs with sessasn_strict.
collision_strict_max_ip_used_for_user	409	Conflict	No more unique IPs available.	Occurs with sessipcollision_strict.

5. Payload Too Large (HTTP 413)

Error Code	Status	Message	Description
max_ips_reached_for_user	413	Max IPs Reached	Internal limit of 2000 unique IPs reached.

6. Internal Server Errors (HTTP 500)

Error Code	Status	Message	Description
internal_server_error	500	Internal Server Error	Generic internal error.
unknown	500	Internal Server Error	Unknown internal error.

7. Bad Gateway Errors (HTTP 502)

Error Code	Status	Message	Description
bad_gateway	502	Bad Gateway	Generic gateway connection issue.
tunnel_failed	502	Bad Gateway	Failed to establish tunnel.
dns_resolve_failed	502	Bad Gateway	Failed to resolve target hostname.
no_peers_available	502	No Peers Available	No proxies match your filters.

8. Service Unavailable (HTTP 503)

Error Code	Status	Message	Description
peer_busy	503	Peer Busy	Selected proxy peer is busy.
peer_not_found	503	Peer Not Found	Requested proxy peer not found.

9. Gateway Timeout (HTTP 504)

Error Code	Status	Message	Description	Action
peer_timeout	504	Peer Timeout	Request to peer timed out.	Retry or change IP.
gateway_timeout	504	Gateway Timeout	Gateway request timed out.	Contact support.

10. SOCKS5 Specific Errors

Note: These errors are primarily for SOCKS5 protocol and may not apply to HTTP proxy clients.

Error Code	Status	Message	Description
N/A	5	SOCKS5 Error	Generic SOCKS5 protocol error.
N/A	5	I/O error	Input/output error in SOCKS5 connection.
N/A	5	UDProxy error	UDP proxy protocol error.
N/A	5	Protocol error	Generic protocol error.

Error Response Format

Errors are returned with custom headers to help you debug via code.

• HTTP Status Code: Standard HTTP status (407, 400, 502, etc.)
• Header: X-Anyip-Error containing the error code.
• Body: Plain text description.

Example Response

< HTTP/1.1 407 Proxy Authentication Required
< x-anyip-error: 407 Proxy Authentication Required (code: region_country_is_missing)
< proxy-authenticate: Basic realm="anyIP"

Troubleshooting Guide

1. 407 Errors: Check your username/password and ensure you aren’t using invalid flags (e.g., region_ without country_).
2. 400 Errors: Check your flag syntax (e.g., sesstime_ must be a number).
3. 502/503/504 Errors: These are usually temporary network issues or empty pools. Try rotating your IP or relaxing your targeting (e.g., remove city_ or asn_).
4. 409/413 Errors: You have hit strict collision limits or account limits. Reset your session or rotate your IP.