Proxy errors

An HTTP status tells a client what kind of failure occurred. Custom headers add a code and message that explain the cause. For example, a client receiving 429 with CONNECTION_LIMIT can reduce its concurrent connections instead of changing credentials.

Use Overview → Proxy errors to choose the header names and what each error says. These settings are optional and apply to all proxy clusters, not individual customers or packages.

Configure one error

You need permission to edit settings. Administrators with view-only access can inspect the configuration but cannot save changes.

1. Set Error code header to X-Proxy-Error-Code and Error message header to X-Proxy-Error-Message. These are example names, not defaults.
2. Search for 114. The description under Connection limit exceeded explains when this error occurs.
3. Enter CONNECTION_LIMIT as the custom code and Too many active connections. as the custom message.

Open full size

Example configuration using test data. Search narrows the table without removing other mappings.

1. 1These names become HTTP response headers.
2. 2The internal error stays 114; you choose the public code and message.

4. Select error 114 in Header preview, check the values, and click Save changes.
5. Restart the proxy instances to load the saved configuration.

Configured means the header names and both row values are complete. The preview includes unsaved edits. Neither confirms that a running proxy has loaded the settings.

Open full size

Check the preview before saving. Existing proxy processes keep their previous configuration until restarted.

1. 1Preview shows the two headers for the selected error.
2. 2Save the changes, then restart the proxy instances.

Header names must be different, valid ASCII names of at most 64 characters; protocol headers such as Connection are reserved. Codes accept up to 64 ASCII letters, digits, dots, underscores, or hyphens. Messages accept up to 512 printable ASCII characters, without line breaks. Values are literal text, not templates. Do not include credentials or private backend details.

What the proxy sends

At startup, the proxy reads the settings from the API. When it encounters a configured error, it looks up the internal code and adds your two headers to the HTTP error response. The HTTP status and response body stay unchanged.

To check this example, use a test account whose concurrent connection slots are already occupied. Keep those connections open, then send another authenticated request:

−+×

RequestGET http://ip-api.com/json

curl 'http://ip-api.com/json' \
  --include \
  --proxy 'http://{proxy_host}:{proxy_port}' \
  --proxy-user '{proxy_username}:{proxy_password}'

−+×

Response429 Too Many Requests

HTTP/1.1 429 Too Many Requests
Connection: close
X-Proxy-Error-Code: CONNECTION_LIMIT
X-Proxy-Error-Message: Too many active connections.

Replace placeholders in braces with your values. Responses use synthetic example data.

Replace the gateway and credentials with your test values. This is an illustrative response from the proxy, not from ip-api.com.

Here, 429 is the HTTP status, 114 is the internal error, and CONNECTION_LIMIT is your public code. The body is empty. Without an exceeded connection limit, this request should not produce this error. Release the occupied slots before retrying safe requests.

If headers are missing

Check that both header names and both row values are saved, and that the proxy was restarted. Successful responses and ordinary errors returned by destination sites do not receive these headers. SOCKS5 replies do not carry them either.

HTTP CONNECT refusals can include headers before a tunnel is established. Once a final response has started or a tunnel is open, the proxy cannot add a new HTTP error response. A disconnected client cannot receive one. See proxy troubleshooting for other failure paths.

Turn it off

Use Clear on a row to disable that mapping. To disable all custom error headers, empty either header-name field. Save and restart the proxy instances in both cases.