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

# Errors

> Error codes and troubleshooting

## HTTP Status Codes

| Status | Category            | Description                       |
| ------ | ------------------- | --------------------------------- |
| 400    | Bad Request         | Invalid parameter format or value |
| 407    | Proxy Auth Required | Authentication failed             |
| 500    | Internal Error      | Server-side failure               |
| 502    | Bad Gateway         | Target server unreachable         |
| 503    | Service Unavailable | No proxy available for location   |

***

## Authentication Errors (407)

| Error Code             | Description                    |
| ---------------------- | ------------------------------ |
| `INVALID_CREDENTIALS`  | Username or password incorrect |
| `SUBSCRIPTION_EXPIRED` | Subscription has expired       |
| `TRAFFIC_EXHAUSTED`    | Traffic quota exceeded         |
| `IP_NOT_WHITELISTED`   | IP not in whitelist            |

***

## Proxy Errors (5xx)

| Status | Error Code           | Description                               |
| ------ | -------------------- | ----------------------------------------- |
| 500    | `INTERNAL_ERROR`     | Server encountered an unexpected error    |
| 502    | `TARGET_UNREACHABLE` | Cannot connect to target server           |
| 503    | `NO_PROXY_AVAILABLE` | No proxy available for specified location |

***

## Parameter Format Errors

HTTP `400 Bad Request`:

| Error Code                  | Cause                              | Example                   |
| --------------------------- | ---------------------------------- | ------------------------- |
| `EMPTY_CREDENTIAL`          | Empty username                     | `:password@...`           |
| `INVALID_CREDENTIAL_PREFIX` | Username doesn't start with `sub_` | `user_xxx:...`            |
| `LEADING_DASH`              | Parameters start with `-`          | `sub_xxx--country-US:...` |
| `TRAILING_DASH`             | Parameters end with `-`            | `sub_xxx-country-US-:...` |
| `CONSECUTIVE_DASH`          | Contains `--`                      | `sub_xxx-country--US:...` |
| `INCOMPLETE_PAIR`           | Missing parameter value            | `sub_xxx-country:...`     |
| `EMPTY_PARAM_NAME`          | Empty parameter name               | `sub_xxx--US:...`         |
| `EMPTY_PARAM_VALUE`         | Empty parameter value              | `sub_xxx-country-:...`    |
| `TOO_MANY_PARAMS`           | More than 10 parameters            | -                         |

## Parameter Value Errors

HTTP `400 Bad Request`:

### country

| Error Code            | Cause                 |
| --------------------- | --------------------- |
| `INVALID_COUNTRY`     | Not a 2-letter code   |
| `UNSUPPORTED_COUNTRY` | Country not available |

### state

| Error Code               | Cause                          |
| ------------------------ | ------------------------------ |
| `STATE_REQUIRES_COUNTRY` | `state` used without `country` |
| `INVALID_STATE`          | State name not recognized      |

### city

| Error Code              | Cause                         |
| ----------------------- | ----------------------------- |
| `CITY_REQUIRES_COUNTRY` | `city` used without `country` |
| `INVALID_CITY`          | City name not recognized      |

### session

| Error Code          | Cause                                |
| ------------------- | ------------------------------------ |
| `SESSION_TOO_SHORT` | Less than 4 characters               |
| `SESSION_TOO_LONG`  | More than 20 characters              |
| `INVALID_SESSION`   | Contains non-alphanumeric characters |

### ttl

| Error Code         | Cause              |
| ------------------ | ------------------ |
| `INVALID_TTL`      | Non-integer value  |
| `TTL_OUT_OF_RANGE` | Value outside 1-60 |

### timeout

| Error Code             | Cause               |
| ---------------------- | ------------------- |
| `INVALID_TIMEOUT`      | Non-integer value   |
| `TIMEOUT_OUT_OF_RANGE` | Value outside 1-120 |

## Troubleshooting

<AccordionGroup>
  <Accordion title="407 Proxy Authentication Required">
    **Causes:** `INVALID_CREDENTIALS`, `SUBSCRIPTION_EXPIRED`, `TRAFFIC_EXHAUSTED`, `IP_NOT_WHITELISTED`

    **Solutions:**

    1. Verify credentials in [Dashboard](https://turnoxy.com/dashboard)
    2. Check subscription status and remaining traffic
    3. Verify whitelisted IP if using IP whitelist auth
  </Accordion>

  <Accordion title="400 Bad Request">
    **Causes:** Malformed parameter string or invalid values.

    **Solutions:**

    1. Check parameter name typos
    2. Verify value formats
    3. Remove leading/trailing dashes
    4. Ensure all parameters have values
  </Accordion>

  <Accordion title="502 Bad Gateway">
    **Causes:** `TARGET_UNREACHABLE` - target server cannot be reached.

    **Solutions:**

    1. Verify target URL is correct and accessible
    2. Increase `timeout` parameter
    3. Check if target blocks proxy IPs
  </Accordion>

  <Accordion title="503 Service Unavailable">
    **Causes:** `NO_PROXY_AVAILABLE` - no proxy available for specified location.

    **Solutions:**

    1. Try broader location (country instead of city)
    2. Remove geo restrictions temporarily
    3. Contact support
  </Accordion>

  <Accordion title="500 Internal Error">
    **Causes:** `INTERNAL_ERROR` - unexpected server-side failure.

    **Solutions:**

    1. Retry the request
    2. If persistent, contact support
  </Accordion>
</AccordionGroup>