407 Proxy Authentication Required: Ogni Causa e Come Risolverla

HTTP 407 ha esattamente un significato: il proxy davanti a te ha rifiutato le tue credenziali. Questo singolo fatto elimina la maggior parte delle deviazioni errate — ecco il resto della mappa.

HTTP 407 Proxy Authentication Required ha esattamente un significato, ed è più ristretto di quanto la maggior parte delle persone supponga: un proxy tra te e internet ha rifiutato la richiesta perché mancano credenziali valide per il proxy stesso. Il sito di destinazione non è mai stato contattato. Non ha mai visto la tua richiesta, non ha mai preso una decisione e non può essere la causa. Risolvere un 407 significa quindi sempre correggere la configurazione del tuo proxy — e l'elenco delle cose che possono essere sbagliate è breve e completamente enumerabile. Questa guida percorre l'intero elenco, con le correzioni specifiche per strumento che causano più problemi alle persone.

Leggi prima l'intestazione Proxy-Authenticate

Secondo la specifica HTTP (RFC 9110), un 407 deve essere accompagnato da un'intestazione Proxy-Authenticate che descrive come autenticarsi — tipicamente qualcosa come Proxy-Authenticate: Basic realm="Access to internal site". Il tuo client deve quindi ripetere la richiesta con un'intestazione Proxy-Authorization. Vale la pena memorizzare questa coppia, perché è ciò che distingue il 407 dal suo vicino: un 401 proviene dal server di origine e abbina WWW-Authenticate con Authorization, mentre il 407 proviene da un intermediario e utilizza le versioni prefissate con Proxy-. Se stai guardando un'intestazione WWW-Authenticate, stai eseguendo il debug del salto sbagliato.

# See exactly which hop is refusing you, and what scheme it wants
curl -v -x http://USER:PASS@gate.quantumproxies.io:8000 https://httpbin.org/ip

# Response you are looking for on failure:
#   HTTP/1.1 407 Proxy Authentication Required
#   Proxy-Authenticate: Basic realm="..."
#
# Response you want on success: your exit IP, not your own
#   {"origin": "203.0.113.45"}

Se curl -x con credenziali restituisce il tuo IP di uscita, il proxy e le credenziali sono entrambi a posto — e qualsiasi 407 che vedi ancora in un'applicazione è la configurazione dell'applicazione stessa, non quella del proxy. Questo singolo test divide il problema a metà in circa dieci secondi.

Causa 1: le credenziali sono assenti, errate o nel posto sbagliato

La causa più comune è anche la più noiosa. Le credenziali appartengono all'URL del proxy, prima dell'host, nella forma user:pass@host:port — e la libreria client costruisce l'intestazione Proxy-Authorization da esse. Copiare un endpoint da una dashboard senza le credenziali, o incollare la password del tuo account invece della password del proxy (di solito sono diverse), produce un 407 immediato e permanente su ogni richiesta.

import requests

proxy = "http://USER:PASS@gate.quantumproxies.io:8000"
proxies = {"http": proxy, "https": proxy}

r = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=15)
print(r.status_code, r.json())   # 200 and the exit IP = auth is correct

Controlla anche la porta. I fornitori espongono porte diverse per endpoint rotanti e fissi, e per HTTP rispetto a SOCKS5; colpire quella sbagliata con credenziali valide può ancora restituire 407 perché quel listener si aspetta un formato di identità diverso. Se non sei sicuro di quale protocollo stai utilizzando, il nostro spiegatore su SOCKS5 rispetto ai proxy HTTP illustra le differenze.

Causa 2: caratteri speciali mai codificati in percentuale

Questo costa alle persone interi pomeriggi. Un URL del proxy è un URL, quindi qualsiasi carattere riservato nel tuo nome utente o password deve essere codificato in percentuale o il parser dividerà la stringa nel posto sbagliato. Una password contenente @ termina prematuramente la sezione userinfo e il tuo client tenta di connettersi a un host che non esiste; un : divide il nome utente dalla password nel posto sbagliato.

@ diventa %40 — il singolo colpevole più comune, perché le email sono usate come nomi utente.
: diventa %3A — altrimenti viene letto come separatore nome utente/password.
# diventa %23 — tutto ciò che segue viene trattato come un frammento e scartato silenziosamente.
/ diventa %2F e ? diventa %3F — entrambi terminano la sezione dell'autorità.
Uno spazio letterale diventa %20. Se la tua password ne contiene uno, cambiala invece.

from urllib.parse import quote

user = quote("team@example.com", safe="")   # team%40example.com
pwd  = quote("p@ss:w#rd", safe="")          # p%40ss%3Aw%23rd

proxy = f"http://{user}:{pwd}@gate.quantumproxies.io:8000"

Lista di controllo che mappa i sintomi di 407 proxy authentication required alle loro vere cause, inclusi fallimenti dei tunnel, cambiamenti delle whitelist e impostazioni proxy per strumento — Stesso codice di stato, sei diversi errori. Abbina il sintomo a sinistra prima di cambiare qualsiasi cosa.

Causa 3: autenticazione whitelist e un IP che si è spostato

La maggior parte dei fornitori supporta due modalità di autenticazione: credenziali nell'URL o whitelist IP, dove autorizzi l'indirizzo pubblico del tuo server nella dashboard e non invii alcuna credenziale. QuantumProxies supporta entrambi. La modalità di fallimento è specifica e molto riconoscibile: tutto ha funzionato per settimane, poi ogni richiesta ha iniziato a restituire 407 senza un cambiamento di codice. Questo è il tuo IP pubblico che cambia — un rinnovo del lease DHCP in ufficio, un nuovo gateway NAT dopo un ridistribuzione nel cloud, un tether mobile o un runner CI che ottiene un nuovo indirizzo a ogni lavoro.

Conferma ciò prima di eseguire il debug di qualsiasi altra cosa: recupera il tuo indirizzo pubblico corrente con curl -sS https://api.ipify.org, confrontalo con la whitelist e riaggiungilo se è diverso. Se il tuo IP di uscita non è stabile — i runner CI e i gruppi di autoscaling raramente lo sono — passa quell'ambiente all'autenticazione user:pass, che viaggia con la configurazione invece che con la rete. L'altra metà di questa trappola è mescolare le modalità: alcuni gateway rifiutano le credenziali su un endpoint solo whitelist, quindi inviare entrambe può fallire dove inviarne nessuna ha successo.

Causa 4: HTTPS passa attraverso un tunnel CONNECT

Un 407 che appare solo su URL https://, spesso come l'errore Python OSError: Tunnel connection failed: 407 Proxy Authentication Required, ha una causa strutturale. Le richieste HTTP semplici vengono inoltrate dal proxy, ma le richieste HTTPS aprono prima un tunnel con una richiesta CONNECT — e quel CONNECT trasporta la propria intestazione Proxy-Authorization. Se la tua configurazione ha impostato solo un proxy HTTP, o ha impostato credenziali su uno schema e non sull'altro, il tunnel viene tentato in modo anonimo e rifiutato prima che TLS inizi.

La regola è semplice: configura sempre entrambi gli schemi con le stesse credenziali. In Python significa entrambe le chiavi nel dizionario proxies; nella shell significa HTTP_PROXY e HTTPS_PROXY; in npm significa proxy e https-proxy. Nota che HTTPS_PROXY prende quasi sempre uno schema http:// — lo schema descrive come parli al proxy, non cosa stai recuperando attraverso di esso.

// Node 18+ with undici: one dispatcher covers http and https targets
import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent(
  "http://USER:PASS@gate.quantumproxies.io:8000"
);

const res = await fetch("https://httpbin.org/ip", { dispatcher });
console.log(res.status, await res.json());

Causa 5: lo strumento ha la propria configurazione proxy

Le variabili d'ambiente non sono universali. Molti strumenti leggono il proprio file di configurazione e ignorano completamente la shell, il che produce lo stato esasperante in cui curl funziona e la tua build no. Un problema di lunga data con GitHub Desktop è l'illustrazione da manuale: uno sviluppatore dietro un proxy aziendale aveva impostato il proxy in .gitconfig e nell'ambiente, eppure l'accesso continuava a fallire con un 407 e net::ERR_TUNNEL_CONNECTION_FAILED — perché la configurazione git autenticava solo git, mentre il browser incorporato che eseguiva il flusso OAuth non aveva credenziali proxy proprie. Ogni sottosistema ha bisogno di essere informato separatamente.

# shell-wide (respected by curl, wget, pip, most SDKs)
export HTTP_PROXY="http://USER:PASS@gate.quantumproxies.io:8000"
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal"

# npm - both keys, or https installs will 407
npm config set proxy       "$HTTP_PROXY"
npm config set https-proxy  "$HTTPS_PROXY"

# git
git config --global http.proxy  "$HTTP_PROXY"
git config --global https.proxy "$HTTPS_PROXY"

# apt - /etc/apt/apt.conf.d/95proxies
# Acquire::http::Proxy  "http://USER:PASS@gate.quantumproxies.io:8000";
# Acquire::https::Proxy "http://USER:PASS@gate.quantumproxies.io:8000";

Postman — Impostazioni, Proxy, configurazione proxy personalizzata, quindi seleziona l'autenticazione proxy e inserisci nome utente e password. L'interruttore proxy di sistema non trasporta le credenziali.
.NET / C# — un WebException che legge "Il server remoto ha restituito un errore: (407)" significa che il WebProxy non ha Credentials; impostale esplicitamente o usa le credenziali di rete predefinite.
Java — proprietà di sistema http.proxyUser e http.proxyPassword, oltre a un Authenticator, poiché la JVM non legge le variabili della shell.
Browser — un 407 memorizzato nella cache può persistere dopo aver corretto le credenziali; ricarica forzatamente o cancella la cache prima di supporre che la correzione sia fallita.
Docker — il demone e la build necessitano entrambi di impostazioni proxy, e sono configurati in posti diversi.

Una nota sulla sicurezza mentre modifichi tutti questi file: le credenziali in un file di configurazione globale git o npm finiscono in testo semplice, e gli URL proxy con password incorporate trapelano nella cronologia della shell, nei log CI e nei tracciati degli errori. Su macchine con un indirizzo stabile, la whitelist IP evita completamente il segreto.

Confronto tra autenticazione proxy user:pass e autenticazione whitelist IP, mostrando i compromessi di portabilità e gestione dei segreti — Le credenziali viaggiano con la tua configurazione; le whitelist viaggiano con la tua rete. Scegli per ambiente, mai entrambe contemporaneamente.

Un 407 non è mai colpa del sito di destinazione

Vale la pena ripeterlo, perché ti salva dall'inseguire fantasmi. Se stai ricevendo 407, nessuna quantità di rotazione degli user agent, aggiunta di intestazioni o cambio di paesi di uscita aiuterà — la richiesta non ha ancora lasciato il tuo proxy. I blocchi che provengono dal sito di destinazione appaiono diversi: un 403 Forbidden significa che il sito ti ha rifiutato, e un 429 Too Many Requests significa che sei andato troppo veloce. Diagnostica quale dei tre hai realmente prima di scrivere qualsiasi codice. E se Python sta lanciando ProxyError o SSLError invece di un pulito 407, la nostra guida a debugging ProxyError in Requests copre i fallimenti a livello di trasporto.

Domande frequenti

Come risolvo 407 Proxy Authentication Required?

Inserisci credenziali valide nell'URL del proxy come http://user:pass@host:port, codificando in percentuale qualsiasi carattere riservato, e configura sia le impostazioni proxy HTTP che HTTPS. Se il tuo fornitore utilizza invece la whitelist IP, autorizza il tuo IP pubblico corrente e non inviare credenziali. Verifica con curl -x contro un servizio di eco IP prima di toccare il codice della tua applicazione.

Cosa significa 407 Proxy Authentication Required?

Significa che un proxy intermedio ha rifiutato la richiesta per mancanza di credenziali proxy valide. La risposta include un'intestazione Proxy-Authenticate che nomina lo schema, e il client è tenuto a riprovare con Proxy-Authorization. È distinto dal 401, che proviene dal server di destinazione piuttosto che dal proxy intermedio.

Come risolvo l'errore npm 407?

Imposta entrambe le chiavi: npm config set proxy e npm config set https-proxy, ciascuna con l'URL completo http://user:pass@host:port. Il traffico del registro è HTTPS, quindi un'impostazione solo HTTP fallisce al tunnel CONNECT. Codifica in percentuale i caratteri speciali nella password e controlla se un .npmrc a livello di progetto sta sovrascrivendo quello globale.

Perché Python solleva Tunnel connection failed: 407?

Perché la richiesta HTTPS ha aperto un tunnel CONNECT che non trasportava credenziali proxy. Imposta entrambe le chiavi http e https del dizionario proxies allo stesso URL autenticato. Controlla anche se HTTP_PROXY o HTTPS_PROXY nell'ambiente sta sovrascrivendo il tuo dizionario — imposta session.trust_env = False per escluderlo.

Come imposto l'autenticazione proxy in Postman?

Apri Impostazioni, vai alla scheda Proxy, abilita la configurazione proxy personalizzata, inserisci host e porta, quindi seleziona la casella di autenticazione proxy e aggiungi nome utente e password. Affidarsi all'interruttore proxy di sistema è l'errore comune — instrada il traffico attraverso il proxy ma non fornisce mai le credenziali, quindi ogni richiesta restituisce 407.

Cinque cause coprono essenzialmente ogni 407 in circolazione: credenziali mancanti, caratteri speciali non codificati, un IP in whitelist che è cambiato, un tunnel CONNECT non autenticato e uno strumento con la propria configurazione. Lavorale in quell'ordine e il codice di stato scompare — poi puoi iniziare a preoccuparti di cosa pensa il sito di destinazione di te.

Ottieni proxy residenziali con autenticazione user:pass o whitelist IP