Configure a proxy for hCaptcha token workers

Use the token request proxy object, keep worker and API transport proxies distinct, and redact network credentials from diagnostics.

Supply worker networking on the request

The easycaptcha token request can include a proxy object. It supports the schemes http, https, and socks5, a host, a numeric port from 1 to 65535, and optional username and password. These fields are forwarded for the token worker’s challenge traffic.

{
  "type": "hcaptcha_token",
  "sitekey": "YOUR_SITEKEY",
  "url": "https://your-site.example/login",
  "proxy": {
    "scheme": "http",
    "host": "proxy.example",
    "port": 8080,
    "username": "PROXY_USER",
    "password": "PROXY_PASSWORD"
  }
}

Use actual authorized networking configuration rather than the placeholder host. Consult the API reference for validation rules. Your customer API key remains a separate Bearer credential.

Keep two transport paths distinct

A proxy configured in requests, httpx, axios, or curl_cffi controls your application’s connection to easycaptcha. The JSON proxy field controls the worker connection described by the task. Setting the local client proxy does not populate the worker field automatically.

This distinction changes troubleshooting. An application-to-API timeout may occur before task admission. A worker network failure can appear after a task ID exists. Preserve that ID and the stage of failure, rather than labeling both “proxy broken” and blindly resubmitting.

Make credential handling part of the integration

Redact proxy passwords from request-body logs and support transcripts. A request body that was previously safe to record may become sensitive after the proxy field is added. Avoid embedding credentials in sample URLs or filenames.

Record the proxy configuration identifier in your own systems if you need to correlate outcomes, rather than copying its password into every event. Keep changes to that configuration visible during an evaluation so shifts in performance are not attributed to the solver alone.

Test the workflow you deploy

Validate construction using a fake network configuration before a live evaluation, then test an approved working proxy and a definite failure case. Confirm that pending work is retrieved by its existing ID and that unknown creation outcomes do not trigger automatic duplication.

The enterprise guide uses the same optional object. Proxy versus proxyless task choices explains why vendor labels are not universal contracts.