In breve: il server dice "devi pagare prima che questa risorsa diventi disponibile".
HTTP 402 Payment Required è uno dei codici di stato più misteriosi e sottoutilizzati nelle specifiche HTTP. A differenza dei suoi fratelli ben noti come 404 (Not Found) o 401 (Unauthorized), il codice 402 è stato progettato con una visione lungimirante: abilitare meccanismi di pagamento nativi sul web.
Quando un server restituisce una risposta 402, comunica un messaggio chiaro: "Questa risorsa esiste, hai le credenziali corrette, ma devi pagare per accedervi." Questo è fondamentalmente diverso dagli altri codici di errore client 4xx, che in genere indicano problemi di autenticazione o autorizzazione.
Il codice di stato 402 ha una storia affascinante che riflette l'ottimismo iniziale sul commercio web:
L'HTTP 402 è stato incluso nella specifica originale HTTP/1.1 (RFC 2068, pubblicata nel 1997) con la nota esplicita che era "riservato per un uso futuro". L'idea era che, con l'evoluzione dell'e-commerce, sarebbe diventato essenziale un modo standardizzato per richiedere il pagamento. Gli architetti dell'HTTP prevedevano che i micropagamenti digitali sarebbero diventati comuni.
Nonostante facesse parte della specifica per oltre due decenni, il 402 è rimasto in gran parte inutilizzato. La mancanza di sistemi di pagamento digitali standardizzati e la complessità di implementare flussi di pagamento multipiattaforma hanno fatto sì che i siti web sviluppassero le proprie soluzioni proprietarie.
Con l'ascesa delle criptovalute, delle stablecoin come USDC e di protocolli come x402, il codice di stato 402 sta finalmente trovando il suo scopo. La moderna tecnologia blockchain fornisce il tassello mancante: un livello di pagamento standardizzato e programmabile che può funzionare perfettamente con l'HTTP.
Comprendere le differenze tra questi codici di stato è fondamentale per un corretto sviluppo web e per la progettazione di API:
| Stato | Significato | Scenario Comune | Azione Utente Richiesta |
|---|---|---|---|
| 401 Unauthorized | Autenticazione richiesta | Non loggato, token scaduto | Accedi o aggiorna le credenziali |
| 403 Forbidden | Autenticato ma non autorizzato | L'account non ha i permessi | Richiedi l'accesso all'amministratore |
| 402 Payment Required | Pagamento richiesto | Pay-per-view, micropagamenti | Completa la transazione di pagamento |
| 404 Not Found | Risorsa non trovata | Link rotto, contenuto rimosso | Controlla l'URL o contatta il supporto |
Nonostante faccia parte della specifica HTTP dal 1997, il codice di stato 402 ha visto un'adozione minima. Ecco perché:
La specifica HTTP ha definito il codice di stato ma non ha specificato COME i pagamenti dovrebbero funzionare. Senza un header di pagamento standardizzato, un formato di richiesta o una struttura di risposta, ogni implementazione era incompatibile con le altre.
I pagamenti con carta di credito richiedono integrazioni complesse con processori di pagamento, conformità PCI, logica di fatturazione ricorrente e sistemi di prevenzione delle frodi. Questo sovraccarico rendeva il 402 impraticabile per le piccole transazioni.
I sistemi di pagamento tradizionali hanno commissioni di transazione minime che rendono i micropagamenti (sotto 1€) economicamente non fattibili. Una commissione di accesso agli articoli di 0,05€ non funziona quando il costo della transazione è di 0,30€.
Le aziende hanno sviluppato alternative: modelli di abbonamento, contenuti supportati da pubblicità, token di accesso basati su OAuth o overlay di paywall personalizzati che restituiscono 200 OK con controllo degli accessi basato su JavaScript.
Secondo l'RFC 9110 (l'attuale specifica HTTP), il codice di stato 402 è definito come segue:
Sebbene non ufficialmente standardizzati, le implementazioni in genere includono:
X-Payment-Required: Informazioni sul pagamento richiestoX-Price: L'importo da pagareX-Currency: La valuta per il pagamento (USD, USDC, ecc.)X-Payment-Address: L'indirizzo a cui inviare il pagamentoIl protocollo x402 standardizza questi header con un sistema completo di negoziazione del pagamento. Quando ricevi una risposta 402 da un server abilitato a x402, la risposta include tutte le informazioni necessarie per completare il pagamento automaticamente.
Il codice di stato 402 è particolarmente adatto per diversi casi d'uso emergenti:
Le API pay-per-call possono usare il 402 per addebitare ogni richiesta. Servizi AI, API di dati e funzionalità premium possono essere consultati senza abbonamenti — paghi solo per quello che usi.
Articoli di giornale, documenti di ricerca e contenuti premium possono essere sbloccati con piccoli pagamenti. Nessun abbonamento richiesto — basta pagare per i singoli contenuti.
Agenti autonomi e bot possono accedere a risorse a pagamento senza intervento umano. La risposta 402 fornisce tutto il necessario per l'elaborazione automatica del pagamento.
Le applicazioni Web3 possono usare il 402 per limitare l'accesso alle risorse decentralizzate, con pagamenti regolati on-chain in USDC o altre stablecoin.
Acquisti in-game, asset digitali e funzionalità premium possono essere sbloccati con pagamenti istantanei attivati dalle risposte 402.
Tutti i moderni browser riconoscono il 402 come un codice di stato HTTP valido, sebbene non abbiano una gestione integrata per esso:
| Piattaforma | Stato | Note |
|---|---|---|
| Chrome/Edge | ✅ Riconosciuto | Visualizzato come errore client |
| Firefox | ✅ Riconosciuto | Visualizzato come errore client |
| Safari | ✅ Riconosciuto | Visualizzato come errore client |
| Node.js/fetch | ✅ Pienamente Supportato | Può essere gestito a livello programmatico |
| cURL | ✅ Pienamente Supportato | Restituisce il codice di stato 402 |
Sebbene i browser non gestiscano automaticamente i pagamenti 402, le librerie client-side e le estensioni dei browser possono intercettare le risposte 402 e attivare i flussi di pagamento.
Questo è esattamente ciò che risolve x402: convertire il segnale di "pagamento richiesto" in un'esperienza di checkout automatica e senza intoppi.
L'intero flusso avviene in pochi secondi, spesso senza che sia richiesta alcuna interazione da parte dell'utente. Questa è la visione per cui l'HTTP 402 è stato progettato, finalmente realizzata attraverso la moderna infrastruttura delle criptovalute.
Se sei uno sviluppatore che desidera implementare il 402 nella propria applicazione, ecco una panoramica rapida:
// Esempio Express.js
app.get('/premium-content', (req, res) => {
if (!isPaid(req)) {
return res.status(402).json({
error: 'Pagamento richiesto',
price: '0.10',
currency: 'USDC',
paymentAddress: '0x...'
});
}
res.json({ content: 'I dati premium sono qui' });
});// Esempio JavaScript
const response = await fetch('/premium-content');
if (response.status === 402) {
const paymentInfo = await response.json();
// Attiva il flusso di pagamento
await processPayment(paymentInfo);
// Riprova con la prova di pagamento
return fetch('/premium-content', {
headers: { 'X-Payment-Proof': proof }
});
}Con protocolli come x402, il futuro dell'HTTP 402 appare luminoso:
La visione originale del web dei pagamenti nativi sta finalmente diventando realtà, e l'HTTP 402 è al centro di questa trasformazione.