> ## Documentation Index
> Fetch the complete documentation index at: https://anyip.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy Client Errors

> Comprehensive list of error codes, HTTP statuses, and troubleshooting steps for the anyIP proxy

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

```bash theme={null}
< 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.