Skip to main content
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 CodeStatusMessageDescription
wrong_customer_credentials407Auth FailedInvalid username or password provided.
bad_basic_auth_format407Bad Auth FormatBasic authentication header has incorrect format.
ip_whitelisted_bad_port407Auth FailedIP is whitelisted but wrong port was used.

​
Attribute Parsing

Error CodeStatusMessageDescriptionMore Info
bad_attributes_user_missing407Proxy Auth Required’user’ attribute missing.user_xxxx is missing from username.
bad_attributes_type_missing407Proxy Auth Required’type’ attribute missing.type_mobile, type_residential, etc. missing.
bad_attributes_parse_error407Proxy Auth RequiredFailed to parse attributes.Check comma separation.
bad_attributes_session_name_too_long407Bad AuthenticationSession name > 32 chars.Must be 1-32 characters.
bad_attributes_session_name_invalid_character407Bad AuthenticationInvalid chars in session name.Use a-Z and 0-9 only.
region_country_is_missing407Proxy Auth RequiredRegion specified without country.Used region_xxx without country_xx.
city_country_is_missing407Proxy Auth RequiredCity specified without country.Used city_xxx without country_xx.
city_region_is_missing407Proxy Auth RequiredCity specified without region.Used city_xxx without region_xx.
bad_os407Proxy Auth RequiredInvalid operating system.Wrong os_xx flag.

​
Feature/Session Errors

Error CodeStatusMessageDescriptionMore Info
invalid_country_specified407Proxy Auth RequiredInvalid country code.E.g., country_US3.
multi_attr_is_not_supported407Proxy Auth RequiredMultiple attributes not supported.

​
2. Bad Request Errors (HTTP 400)

Status: 400 Bad Request The request is malformed or contains invalid parameters.

​
Request Validation

Error CodeStatusMessageDescription
host_not_supported400Bad HostTarget host is not allowed or invalid.
port_not_supported400Bad PortTarget port is not allowed or invalid.
host_not_found400Bad RequestTarget host could not be found.
bad_asn400Bad RequestInvalid ASN specified.
header_base64_validate_error400Bad RequestBase64 validation failed for header.
header_parse_error400Bad RequestFailed to parse request headers.
header_base64_decode_error400Bad RequestBase64 decoding failed for header.

​
Feature Configuration

Error CodeStatusMessageDescriptionMore Info
bad_coordinates400Bad RequestInvalid lat/lon coordinates.
bad_session_duration_format400Bad RequestInvalid duration format.sesstime_10min is invalid (numbers only).
bad_auto_renew_value400Bad RequestAuto-renew must be boolean.sessreplace_true or sessreplace_false.
session_too_long400Bad RequestDuration > 10080 mins.Max 1 week.
session_too_short400Bad RequestDuration < 1 min.Min 1 minute.
incorrect_session_ip_collision_value400Bad RequestInvalid IP collision value.Must be strict or flexible.
incorrect_session_asn_value400Bad RequestInvalid ASN value.Must be strict or flexible.
incorrect_pool400Bad RequestInvalid pool specified.Check pool_xxx options.
bad_region_name400Bad RequestInvalid region name.
bad_city_name400Bad RequestInvalid city name.
country_not_available400Bad RequestCountry not available.country_xxx unavailable.
feature_not_supported400Bad RequestFeature not supported.Only standard flags supported.
bad_type400Bad RequestInvalid network type.mobile, residential, residentialonly.

​
3. Forbidden Errors (HTTP 403)

Error CodeStatusMessageDescription
host_not_allowed403Bad HostTarget host is forbidden/not allowed.

​
4. Conflict Errors (HTTP 409)

Error CodeStatusMessageDescriptionMore Info
session_asn_ip_exhausted_for_user409ConflictNo more IPs for ASN session.Occurs with sessasn_strict.
collision_strict_max_ip_used_for_user409ConflictNo more unique IPs available.Occurs with sessipcollision_strict.

​
5. Payload Too Large (HTTP 413)

Error CodeStatusMessageDescription
max_ips_reached_for_user413Max IPs ReachedInternal limit of 2000 unique IPs reached.

​
6. Internal Server Errors (HTTP 500)

Error CodeStatusMessageDescription
internal_server_error500Internal Server ErrorGeneric internal error.
unknown500Internal Server ErrorUnknown internal error.

​
7. Bad Gateway Errors (HTTP 502)

Error CodeStatusMessageDescription
bad_gateway502Bad GatewayGeneric gateway connection issue.
tunnel_failed502Bad GatewayFailed to establish tunnel.
dns_resolve_failed502Bad GatewayFailed to resolve target hostname.
no_peers_available502No Peers AvailableNo proxies match your filters.Relax your targeting.

​
8. Service Unavailable (HTTP 503)

Error CodeStatusMessageDescription
peer_busy503Peer BusySelected proxy peer is busy.
peer_not_found503Peer Not FoundRequested proxy peer not found.

​
9. Gateway Timeout (HTTP 504)

Error CodeStatusMessageDescriptionAction
peer_timeout504Peer TimeoutRequest to peer timed out.Retry or change IP.
gateway_timeout504Gateway TimeoutGateway 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 CodeStatusMessageDescription
N/A5SOCKS5 ErrorGeneric SOCKS5 protocol error.
N/A5I/O errorInput/output error in SOCKS5 connection.
N/A5UDProxy errorUDP proxy protocol error.
N/A5Protocol errorGeneric 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.