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.	Relax your targeting.

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

407 Errors: Check your username/password and ensure you aren’t using invalid flags (e.g., region_ without country_).
400 Errors: Check your flag syntax (e.g., sesstime_ must be a number).
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_).
409/413 Errors: You have hit strict collision limits or account limits. Reset your session or rotate your IP.

Getting Started

Core Features

Integration

Reference

Support

Proxy Client Errors

Error Categories

1. Authentication Errors (HTTP 407)

Basic Authentication

Attribute Parsing

Feature/Session Errors

2. Bad Request Errors (HTTP 400)

Request Validation

Feature Configuration

3. Forbidden Errors (HTTP 403)

4. Conflict Errors (HTTP 409)

5. Payload Too Large (HTTP 413)

6. Internal Server Errors (HTTP 500)

7. Bad Gateway Errors (HTTP 502)

8. Service Unavailable (HTTP 503)

9. Gateway Timeout (HTTP 504)

10. SOCKS5 Specific Errors

Error Response Format

Example Response

Troubleshooting Guide

​Error Categories

​1. Authentication Errors (HTTP 407)

​Basic Authentication

​Attribute Parsing

​Feature/Session Errors

​2. Bad Request Errors (HTTP 400)

​Request Validation

​Feature Configuration

​3. Forbidden Errors (HTTP 403)

​4. Conflict Errors (HTTP 409)

​5. Payload Too Large (HTTP 413)

​6. Internal Server Errors (HTTP 500)

​7. Bad Gateway Errors (HTTP 502)

​8. Service Unavailable (HTTP 503)

​9. Gateway Timeout (HTTP 504)

​10. SOCKS5 Specific Errors

​Error Response Format

​Example Response

​Troubleshooting Guide

Error Categories

1. Authentication Errors (HTTP 407)

Basic Authentication

Attribute Parsing

Feature/Session Errors

2. Bad Request Errors (HTTP 400)

Request Validation

Feature Configuration

3. Forbidden Errors (HTTP 403)

4. Conflict Errors (HTTP 409)

5. Payload Too Large (HTTP 413)

6. Internal Server Errors (HTTP 500)

7. Bad Gateway Errors (HTTP 502)

8. Service Unavailable (HTTP 503)

9. Gateway Timeout (HTTP 504)

10. SOCKS5 Specific Errors

Error Response Format

Example Response

Troubleshooting Guide