Skip to content

Claude API Proxy: Base URL, SDK Proxy Settings, Errors

Where a proxy goes in the Claude API client, how it differs from base_url, and how to read the error when a call fails.

base_url and a proxy are two different settings

base_url (or the ANTHROPIC_BASE_URL variable) decides which host the SDK sends requests to. Anthropic’s Python page shows it next to http_client in the same constructor. A proxy decides which network path the request takes to that host. People searching for a Claude API proxy usually need the second one.

Change base_url only for a gateway you run yourself or are authorised to use, because your API key is sent to whatever host you set. Do not point it at an unknown host to make a region error go away.

Where each setting goes

Where each setting goes
ItemWhat it changesWhere the docs show it
base_url / ANTHROPIC_BASE_URLThe host the request goes toPython SDK page: base_url argument or the variable
Python proxyThe network path of one clienthttp_client=DefaultHttpxClient(proxy=...)
Node proxyThe network path of one clientfetchOptions.dispatcher with an undici ProxyAgent
Claude CodeTerminal tool, not the SDKProxy variables and settings.json: see the Claude Code proxy guide

Source: Claude Platform Python and TypeScript SDK pages, read on 17 November 2026. The SDK pages do not list HTTPS_PROXY, so pass the proxy to the client.

Step 1: test the route with curl

Run the commands on the machine that will make the calls. The first must show the country you expect. The second sends no key on purpose: a JSON 401 authentication_error is the documented answer for a key problem, so it shows the request reached the API (our reading). The third uses your key and proves it works through the proxy.

Step 1: test the route with curl

# 1) Which IP and country does Anthropic see? (the proxy's exit)
curl -x "http://USERNAME:PASSWORD@HOST:PORT" https://ipinfo.io/json

# 2) Does the request reach the API? No key on purpose: a JSON 401 authentication_error
#    means the network path works and only the key is missing
curl -s -x "http://USERNAME:PASSWORD@HOST:PORT" https://api.anthropic.com/v1/messages \
  -H "anthropic-version: 2026-10-21" -H "content-type: application/json" \
  -d '{"model":"MODEL_ID","max_tokens":16,"messages":[{"role":"user","content":"Hello, Claude"}]}'

# 3) With your key: a normal message response (use a model ID from Anthropic's models page)
curl -x "http://USERNAME:PASSWORD@HOST:PORT" https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{"model":"MODEL_ID","max_tokens":16,"messages":[{"role":"user","content":"Hello, Claude"}]}'

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets, and MODEL_ID with a model ID from Anthropic’s models page. The anthropic-version value is the one shown on Anthropic’s errors page.

Step 2: Python SDK

Anthropic’s Python page says the SDK sends requests with httpx2 and that you customise proxies by passing your own client as http_client. Use DefaultHttpxClient so the SDK keeps its timeout and connection defaults. A client from the separate httpx package raises TypeError.

The same client fetches ipinfo.io first, so the first printed line shows the exit the SDK really uses. The SDK retries connection errors, 408, 409, 429 and 5xx twice by default; the example lowers that to one so a bad proxy fails faster.

Step 2: Python SDK

# pip install anthropic          (Python 3.10 or later; reads ANTHROPIC_API_KEY from the environment)
import anthropic
from anthropic import Anthropic, DefaultHttpxClient

PROXY = "http://USERNAME:PASSWORD@HOST:PORT"   # percent-encode special characters in the password

http = DefaultHttpxClient(proxy=PROXY)

# 1) Which exit does this client use?
print(http.get("https://ipinfo.io/json").text)

# 2) Same client for the API. Leave base_url alone: this is a proxy, not a gateway.
client = Anthropic(http_client=http, max_retries=1, timeout=30.0)
try:
    message = client.messages.create(
        model="MODEL_ID",              # a model ID from Anthropic's models page
        max_tokens=16,
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
    print(message.content[0].text, message._request_id)
except anthropic.APIConnectionError as e:
    print("Could not reach the API through the proxy:", e.__cause__)
except anthropic.APIStatusError as e:
    print("HTTP", e.status_code, e.response.headers.get("request-id"))

# SOCKS5: pip install "httpx2[socks]", then PROXY = "socks5://USERNAME:PASSWORD@HOST:PORT"

Replace HOST, PORT, USERNAME and PASSWORD with the values from My assets. For SOCKS5, install httpx2[socks] and use the socks5:// line.

Step 3: Node SDK

The TypeScript page documents the Node.js route: create an undici ProxyAgent and pass it as fetchOptions.dispatcher. undici builds the proxy login from the username and password in the address and URL-decodes them first. Bun uses fetchOptions.proxy and Deno uses a client from Deno.createHttpClient; the same page shows both.

Step 3: Node SDK

// npm install @anthropic-ai/sdk undici      (reads ANTHROPIC_API_KEY from the environment)
// Save as check.mjs and run: node check.mjs
import Anthropic from '@anthropic-ai/sdk';
import * as undici from 'undici';

// Wrap special characters of the password with encodeURIComponent()
const proxyAgent = new undici.ProxyAgent('http://USERNAME:PASSWORD@HOST:PORT');

const client = new Anthropic({
  fetchOptions: { dispatcher: proxyAgent },
  maxRetries: 1,
  timeout: 30 * 1000,
});

try {
  const message = await client.messages.create({
    model: 'MODEL_ID',                 // a model ID from Anthropic's models page
    max_tokens: 16,
    messages: [{ role: 'user', content: 'Hello, Claude' }],
  });
  console.log(message.content[0].text, message._request_id);
} catch (err) {
  if (err instanceof Anthropic.APIError) console.log(err.status, err.name);
  else console.log('Network error:', err.message);
}

// SOCKS5: new undici.ProxyAgent('socks5://USERNAME:PASSWORD@HOST:PORT')

Replace the placeholders with the values from My assets. For SOCKS5, use the socks5:// line in the last comment.

What the error means

APIConnectionError, timeout, or no response at all

Check Does ipinfo.io through the same proxy answer, and does the client really use it? In Python the error’s __cause__ holds the underlying exception.

Fix Check HOST, PORT and the protocol (HTTP on 2222, SOCKS5 on 3333 at Proxy302), then pass the proxy to the client as in steps 2 and 3.

Stop when If curl without a key cannot reach the API either, the fault is the proxy or the network, not your code.

407 Proxy Authentication Required

Check Is a special character in the password not encoded, or has the IP’s term ended?

Fix Percent-encode the password in the URL, or copy the details from My assets again and check the end date.

401 authentication_error

Check Anthropic’s errors page ties 401 to the API key: malformed, revoked or expired.

Fix Check the key in the Claude Console. A 401 means the request reached Anthropic, so the proxy itself works.

403 permission_error

Check The errors page describes 403 as a key without permission for the resource; it lists no region-specific error. Is the key limited to a workspace or resource you are not calling?

Fix Check organisation and workspace access in the Console. Separately, compare the exit country from step 1 with the supported-regions list.

Stop when If the exit country is not on the list, no client setting changes that. Use the API only from a supported location.

429, 500, 504 or 529

Check 429 is a rate limit or spend cap, 529 is a temporary overload, 500 and 504 are errors on Anthropic’s side.

Fix These are not proxy faults. The SDK already retries twice; log the request-id header and contact support with it if the error persists.

Region errors: what a proxy can and cannot do

Anthropic publishes a list of supported countries, regions and territories, and says any place not listed is unsupported. The policy also covers people physically located in an unsupported region and companies registered, headquartered or majority-owned there. A proxy changes the network exit; it does not change the policy.

Neither the errors page nor the policy describes how a request’s location is measured, and neither names a region-specific error code. So use the exit country as one thing to check, not as a guarantee: read it with ipinfo.io through the proxy, compare it with the list, and use the API only where you are allowed to. For the account side (phone number, billing country), read the Claude region guide.

With Proxy302: steps

  1. Step 1

    Open the Claude page and pick an IP in a country on Anthropic’s list. A static ISP IP is US$7.99 for 30 days, the same in every country; the order page shows which countries have stock today.

  2. Step 2

    Open My assets and copy HOST, PORT, USERNAME and PASSWORD. Each IP has one protocol, chosen at purchase: HTTP is on port 2222 and SOCKS5 on port 3333.

  3. Step 3

    Run the three curl commands from step 1, then paste the proxy into the Python or Node client. Keep one account on one IP and follow Anthropic’s terms and supported regions.

    Expected result The first command shows the country you bought; the second returns a JSON 401.

FAQ

Should I set ANTHROPIC_BASE_URL to use a proxy?

No. ANTHROPIC_BASE_URL sets the host the SDK calls. A proxy is passed to the HTTP client, as the Python and TypeScript pages show. Change base_url only for a gateway you run or may use.

Does HTTPS_PROXY work with the Claude SDK?

The SDK pages we read do not list it, so pass the proxy to the client. For Claude Code, which is a different tool, the proxy variables are documented; see the Claude Code proxy guide.

Which protocol should I use, HTTP or SOCKS5?

HTTP is the simplest: both code examples take it directly. SOCKS5 works in Python with httpx2[socks] and in Node through undici’s ProxyAgent, but you must have bought the IP as SOCKS5.

I get 403 through the proxy. Is it the region?

Not necessarily. Anthropic’s errors page describes 403 as a key without permission for the resource and lists no region-specific error. Check the key’s access first, then the exit country against the supported list.

Will a proxy make Claude API work from my country?

No. A proxy changes the network exit only. Anthropic’s supported-regions list and policy still apply, and the policy also covers where a person is physically located.

Reference links

8
  1. Claude Platform docs: Python SDK

    Official documentation · Confirmed on:

    Read on 17 November 2026: the SDK sends requests with httpx2; base_url or the ANTHROPIC_BASE_URL variable; http_client=DefaultHttpxClient(proxy=...); DefaultHttpxClient preferred over a raw client; a client from the separate httpx package raises TypeError; two automatic retries by default (max_retries); APIConnectionError and APIStatusError; the _request_id property.

    The page does not describe HTTP_PROXY or HTTPS_PROXY for the SDK.

  2. Claude Platform docs: TypeScript SDK

    Official documentation · Confirmed on:

    Read on 17 November 2026: Configuring proxies: on Node.js create undici.ProxyAgent and pass it as fetchOptions.dispatcher; Bun takes fetchOptions.proxy and Deno a client from Deno.createHttpClient; maxRetries (default 2) and timeout options; APIConnectionTimeoutError on timeout.

  3. Claude API errors

    Official documentation · Confirmed on:

    Read on 17 November 2026: 400 invalid_request_error, 401 authentication_error (key problem), 402 billing_error, 403 permission_error (the key lacks permission for the resource), 404, 413, 429 rate_limit_error, 500 api_error, 504 timeout_error, 529 overloaded_error; JSON error body with a request_id; the request-id response header; SDK retries twice with exponential backoff.

    The page has no error that is specific to a country or region.

  4. Claude Platform docs: Supported regions

    Official documentation · Confirmed on:

    Read on 17 November 2026: the list of countries, regions and territories Anthropic can support access from, for example Japan, Singapore, the United Kingdom and the United States; Ukraine is listed except Crimea, Donetsk and Luhansk.

  5. Anthropic: Supported Regions Policy

    Official documentation · Confirmed on:

    Read on 17 November 2026: any country or region not listed is unsupported; the policy covers persons physically located in an unsupported region and entities incorporated, headquartered or majority-owned there. The page does not describe how location is measured and does not mention proxies.

  6. HTTPX2 docs: Proxies

    Official documentation · Confirmed on:

    Read on 17 November 2026: the proxy parameter on client creation; credentials in the userinfo part of the proxy URL; SOCKS needs pip install 'httpx2[socks]' and a socks5:// URL.

  7. undici docs: ProxyAgent

    Official documentation · Confirmed on:

    Read on 17 November 2026: a string or URL passed to ProxyAgent is the proxy address; without token or auth, the proxy-authorization header is built from the username and password in the URI, URL-decoded; socks5: URIs are handled by Socks5ProxyAgent.

  8. Proxy302 product facts and price list

    Product observation · Confirmed on:

    Product facts file of the site, checked 10 November 2026 against the console, the backend and the price table: static ISP per-IP lease US$7.99 for 30 days, the same in every country; HTTP port 2222 and SOCKS5 port 3333; one protocol per IP; no free trial.

Ready to try it?

Create an account, top up once, then pick rotating residential, static ISP or datacenter IPs and have one running in your browser within minutes.