HTTP 402 Payment Required : signification et usage par x402
402 est le code de statut HTTP pour une requête qui nécessite un paiement avant que le serveur ne la traite. Pendant la majeure partie de son histoire, il n'avait aucun format standard. x402 lui en donne un.
Key takeaways
-
402 Payment Required est une erreur client : la requête est valide, mais le serveur veut d'abord être payé.
-
HTTP/1.1 a réservé 402 pour un usage futur et n'a jamais défini comment le paiement devait fonctionner, donc chaque API l'utilisait différemment.
-
x402 définit les pièces manquantes : un en-tête PAYMENT-REQUIRED avec des conditions lisibles par machine et un paiement signé lors de la nouvelle tentative.
Ce que signifie 402 Payment Required
Une réponse 402 indique au client que la requête elle-même est correcte mais ne sera traitée qu'après paiement. Elle appartient à la famille des 4xx car c'est au client, et non au serveur, d'agir ensuite.
402 diffère de 401 Unauthorized et 403 Forbidden. 401 demande des identifiants, 403 refuse la requête purement et simplement, et 402 demande un paiement.
Pourquoi 402 est resté inutilisé si longtemps
Le code a été réservé lors de la rédaction de HTTP/1.1, avec l'idée qu'une forme de monnaie numérique arriverait plus tard. La spécification n'a jamais précisé ce que devait contenir un corps 402 ni comment un client devait payer, donc les navigateurs n'y ont jamais donné suite.
Faute de format commun, les API qui renvoyaient bien un 402 l'utilisaient comme une simple erreur : un compte à court de crédits, une carte refusée, ou une limite de forfait atteinte.
Quand les API renvoient 402 aujourd'hui
Vous rencontrerez 402 dans deux grands cas de figure.
- Erreurs de facturation de compte : la clé est valide mais le solde, le quota ou l'abonnement ne couvre pas la requête. La solution est de recharger ou de mettre à niveau.
- Devis de paiement à la requête : le serveur renvoie des conditions de paiement, et le client peut payer puis relancer la même requête. C'est ainsi que fonctionne x402.
Comment x402 transforme 402 en flux de paiement
x402 place des conditions lisibles par machine dans un en-tête PAYMENT-REQUIRED : montant, actif, réseau et destinataire. Un client signe une autorisation de stablecoin pour ces conditions, la renvoie dans un en-tête PAYMENT-SIGNATURE, et reçoit la réponse avec un reçu PAYMENT-RESPONSE.
Comme tout l'échange se fait en HTTP classique, un agent d'IA doté d'un wallet peut payer un appel API sans s'inscrire ni stocker de clé API.
Gérer un 402 dans votre client
Vérifiez d'abord la présence d'un en-tête PAYMENT-REQUIRED. S'il est présent, la réponse est un devis x402 qu'un client x402 peut payer. S'il ne l'est pas, lisez le corps de l'erreur : cela signifie généralement que le compte a besoin de plus de crédits ou d'un autre forfait.
FAQ HTTP 402
402 Payment Required est-il une erreur ?
C'est une erreur client de la plage 4xx, mais cela ne signifie pas que la requête était mal formée. Cela signifie qu'un paiement est nécessaire avant que le serveur ne poursuive.
Quelle est la différence entre 402 et 401 ?
401 signifie que le serveur a besoin d'identifiants valides. 402 signifie que le serveur a besoin d'un paiement. Une API peut renvoyer 401 pour une clé incorrecte et 402 pour une clé valide sans solde.
Les navigateurs gèrent-ils 402 automatiquement ?
Non. Les navigateurs affichent un 402 comme n'importe quelle autre page d'erreur. Un paiement automatique nécessite un client qui comprend un protocole tel que x402.
Quelles API utilisent 402 avec x402 ?
Tout serveur qui implémente le protocole x402. RunAPI renvoie des devis x402 sur ses endpoints de modèles d'IA facturés à l'appel, ce qui permet à un agent de payer en USDC la génération d'image, de vidéo, de musique et d'audio.
Pages associées
Testez un 402 que vous pouvez réellement payer
Envoyez une requête à un endpoint RunAPI facturé à l'appel sans clé et observez le devis x402 renvoyé.