HTTP 402 Payment Required: cosa significa e come lo usa x402
402 è il codice di stato HTTP per una richiesta che richiede un pagamento prima che il server la soddisfi. Per gran parte della sua storia non ha avuto un formato standard. x402 gliene dà uno.
Key takeaways
-
402 Payment Required è un errore client: la richiesta è valida, ma il server vuole prima il pagamento.
-
HTTP/1.1 ha riservato il 402 per uso futuro senza mai definire come dovesse funzionare il pagamento, quindi ogni API lo ha usato in modo diverso.
-
x402 definisce le parti mancanti: un header PAYMENT-REQUIRED con termini leggibili da macchina e un pagamento firmato al successivo tentativo.
Cosa significa 402 Payment Required
Una risposta 402 dice al client che la richiesta in sé va bene ma non verrà servita finché non viene effettuato il pagamento. Appartiene alla famiglia 4xx perché è il client, non il server, a dover agire successivamente.
402 è diverso da 401 Unauthorized e 403 Forbidden. 401 chiede credenziali, 403 rifiuta la richiesta senza appello, e 402 chiede un pagamento.
Perché il 402 è rimasto inutilizzato così a lungo
Il codice fu riservato quando venne scritto HTTP/1.1, con l'aspettativa che qualche forma di denaro digitale sarebbe arrivata in seguito. La specifica non ha mai detto cosa dovesse contenere un corpo 402 né come un client dovesse pagare, quindi i browser non hanno mai agito su di esso.
Senza un formato condiviso, le API che restituivano 402 lo usavano come un semplice errore: un account senza crediti, una carta rifiutata o un limite di piano raggiunto.
Quando le API restituiscono 402 oggi
Il 402 si incontra in due situazioni generali.
- Errori di fatturazione dell'account: la key è valida ma il saldo, la quota o l'abbonamento non copre la richiesta. La soluzione è ricaricare o passare a un piano superiore.
- Preventivi a consumo: il server restituisce i termini di pagamento, e il client può pagare e ripetere la stessa richiesta. È così che funziona x402.
Come x402 trasforma il 402 in un flusso di pagamento
x402 inserisce termini leggibili da macchina in un header PAYMENT-REQUIRED: importo, asset, rete e destinatario. Un client firma un'autorizzazione stablecoin per quei termini, la rinvia in un header PAYMENT-SIGNATURE e riceve la risposta con una ricevuta PAYMENT-RESPONSE.
Poiché l'intero scambio è semplice HTTP, un agente IA con un wallet può pagare una chiamata API senza registrarsi né memorizzare una API key.
Gestire un 402 nel tuo client
Controlla prima se è presente un header PAYMENT-REQUIRED. Se c'è, la risposta è un preventivo x402 e un client x402 può pagarlo. Se non c'è, leggi il corpo dell'errore: di solito significa che l'account ha bisogno di più crediti o di un piano diverso.
FAQ su HTTP 402
402 Payment Required è un errore?
È un errore client nell'intervallo 4xx, ma non significa che la richiesta fosse malformata. Significa che serve un pagamento prima che il server continui.
Qual è la differenza tra 402 e 401?
401 significa che il server ha bisogno di credenziali valide. 402 significa che il server ha bisogno di un pagamento. Una API può restituire 401 per una key errata e 402 per una key valida senza saldo.
I browser gestiscono il 402 automaticamente?
No. I browser mostrano un 402 come qualsiasi altra pagina di errore. Il pagamento automatico richiede un client che comprenda un protocollo come x402.
Quali API usano 402 con x402?
Qualsiasi server che implementa il protocollo x402. RunAPI restituisce preventivi x402 sui suoi endpoint di modelli IA a consumo, così un agente può pagare in USDC la generazione di immagini, video, musica e audio.
Pagine correlate
Prova un 402 che puoi davvero pagare
Invia una richiesta a un endpoint RunAPI a consumo senza una key e osserva il preventivo x402 restituito.