Error reference

Every failure returns a status code and an AVO_ code in the response body. The codes are stable, so you can branch on them safely in your own retry logic.

A targeting key your product does not sell is refused with 400 AVO_TARGETING_NOT_SUPPORTED rather than ignored. The one exception is a state or city that the product sells in general but that is not on its location list: that request is served at the nearest level we support, a city at its state and a state at its country.

All error codes

Gateway error codes, meanings and recommended actions
Status	Code	Meaning	What to do
407	AVO_AUTH	The login or password is missing or wrong, or the login part of the username is not 3–32 lowercase letters, digits or underscores. It also covers a CORRECT password used from an address that is not on the proxy user's allowlist: that refusal is deliberately identical, so a leaked password cannot be tested against the allowlist that was switched on to make it useless.	Check the username and password from your dashboard, and check the proxy user's IP allowlist there too; the dashboard says which addresses are permitted. Remember that targeting keys are part of the username.
400	AVO_BAD_TARGETING	The targeting part of the username could not be parsed: an unknown key, a repeated key, a bad value, or a missing dependency such as a city without a state.	The body carries a fixed message; the gateway never echoes your username back. Check your keys and values against the targeting page, which lists every rule.
400	AVO_TARGETING_NOT_SUPPORTED	The targeting parses, but the product you are using does not offer it, for example city targeting on a product that sells country targeting only, or a session lifetime above your product's ceiling.	Drop the unsupported key, lower the value, or use a product that includes it.
400	AVO_BAD_REQUEST	The request itself could not be understood: a malformed request line, a missing host, or a request sent to the gateway as if it were an ordinary web server.	Check that your client is configured as a proxy client rather than sending a direct request.
403	AVO_DISABLED	This proxy user is switched off. Nothing else produces this code.	Switch it back on under Proxies in your dashboard, or connect with a proxy user that is still enabled. The change takes a short while to reach the gateway, so retry after re-enabling.
403	AVO_QUOTA	The GB balance for this product is used up.	Top up more GB. The new balance takes a short while to reach the gateway, so retry a couple of seconds after topping up.
403	AVO_PORT_NOT_ALLOWED	The destination port is not on the permitted list, or it is port 80 on a product that does not carry plain http://.	Use port 80, 443, 8080 and 8443, and https:// where plain http:// is not carried.
403	AVO_TARGET_NOT_ALLOWED	The destination is a private, loopback, link-local or cloud-metadata address, or an IPv6 address written as a literal. The gateway only tunnels to public destinations.	Point the request at a public host. For an IPv6 destination, use its hostname instead of the address. To reach a machine on your own network, connect to it directly rather than through the gateway.
429	AVO_TOO_MANY_CONNECTIONS	Too many connections on this proxy user: either new connections arrived faster than the per-minute rate limit, or the product's ceiling on connections held open at once was reached. Both answer with the same code, so the response does not say which.	Ramp up gradually, reuse open connections instead of opening one per request, and retry with exponential backoff.
502	AVO_NETWORK_ERROR	The request could not be completed. Retry it.	Retry with a short backoff. If one destination fails repeatedly, send us the timestamp and the destination and we will investigate.

What an error looks like

The body is a single line of plain text: the code, a colon, then the message for that code. It is readable in a terminal and simple to match on. Nothing you sent is echoed back, so branch on the code rather than parsing the message.

http

HTTP/1.1 400 Bad Request
Proxy-Agent: Avocado Proxies
Content-Type: text/plain; charset=utf-8
Content-Length: 109
Connection: close

AVO_BAD_TARGETING: Invalid targeting options in username. See the docs for the -cc/-st/-ct/-sid/-ttl syntax.

Allowed destination ports

Tunnelled connections may reach the following ports. Anything else returns 403 AVO_PORT_NOT_ALLOWED.

8044380808443

On residential and mobile, use https:// destinations: a plain http:// request is answered with a redirect to the same address on https://, and a tunnel to port 80 is refused. Premium residential also carries plain http:// destinations.

Retrying well

Retry 502 AVO_NETWORK_ERROR and 429 AVO_TOO_MANY_CONNECTIONS. Use exponential backoff starting around one second, with a cap and a maximum attempt count.
Never retry 400s. A malformed username will be malformed the second time too. Fix the request.
Treat 403 as a stop signal. Quota, a disabled proxy user, blocked ports and blocked destinations need a human decision rather than a tighter loop.
Log the code, not just the status. The status tells you the class of problem; the AVO_ code tells you which one.

Getting help

Send us the timestamp, the proxy user’s login (never the password), the exact error code and the destination you were trying to reach. We keep a counter per destination host and minute for 30 days, and never a path or query string, so the exact URL is the piece only you have; with all four we can line your report up against those counters and the usage records and answer in one go.

support@avocadoproxies.com