Erreurs

L'API x402 utilise de véritables codes d'état HTTP. Chaque erreur possède le même corps JSON, et retry_action indique à votre agent ce qu'il doit faire ensuite.

Corps de l'erreur

Nom	Type	Description
erreur	Chaîne de caractères	Code d'erreur, voir le tableau ci-dessous
message	Chaîne de caractères	Court message lisible par l'utilisateur
réessayable	Booléen	La répétition peut-elle aider ?
retry_action	Chaîne de caractères	Ce qu'il faut faire : `resign`, `retry_same_payment`, `poll`, `wait_and_retry`, `abandon`, `human_required`
retry_after_seconds	Nombre entier	Quand réessayer ; équivaut à `Retry-After` en-tête
payment_state	Chaîne de caractères	`unused`, `in_flight` ou `settled` — que les fonds aient été dérobés (Nouvelles tentatives et idempotence)
authorization_expires_at	Chaîne de caractères	Jusqu'à la date à laquelle votre autorisation est encore valable ; ne signez pas de nouvelle autorisation avant
order_id, operation_id, poll_url	Chaîne de caractères	L'ordre et l'opération auxquels le paiement se rapporte, le cas échéant
bound_wallet	Chaîne de caractères	`quote_bound_to_other_wallet`: le portefeuille qui contient la citation
facilitator_reason	Chaîne de caractères	Motif d'échec d'un virement bancaire, à choisir dans une liste prédéfinie, ou `unknown`
détail	Chaîne de caractères	Détails, par exemple le chemin d'accès au champ invalide : `/items/0/qty: …`

Réponses comportant une nouvelle citation (quote_expired, payment_expired, quote_bound_to_other_wallet) contiennent également les balises de citation et le PAYMENT-REQUIRED en-tête.

{
    "error": "payment_not_settleable",
    "message": "The presented authorization can still be settled",
    "retryable": true,
    "retry_action": "wait_and_retry",
    "retry_after_seconds": 512,
    "payment_state": "unused",
    "authorization_expires_at": "2026-11-02T10:16:00Z"
}

Réessayer les actions

retry_action	Ce qu'il faut faire
`resign`	Signez les nouvelles exigences issues de cette réponse (`PAYMENT-REQUIRED`), ou corrigez la demande
`retry_same_payment`	Envoyez la même demande avec les mêmes `PAYMENT-SIGNATURE`. Ne créez pas de nouvelle page
`poll`	Dans `202` Réponses : sondage `poll_url`
`wait_and_retry`	Recommencez (nouvelle citation, nouvelle signature) au plus tôt le `retry_after_seconds`
`abandon`	Répéter la même demande ne servira à rien.
`human_required`	Contactez le service d'assistance. Ne signez pas de nouvelle autorisation.

Codes d'erreur

erreur	HTTP	retry_action	Quand
`payment_required`	402	`resign`	Un point de terminaison payant a été appelé sans `PAYMENT-SIGNATURE`: la citation figure dans la réponse
`payment_invalid`	402	`abandon`	L'en-tête de paiement est mal formé ou n'est pas conforme à la norme x402 version 2 (`X-PAYMENT` (y compris la version 1) ; réseau, ressource, destinataire, montant ou période de validité incorrects ; échec de la vérification de la signature ; renouvellement ou trafic payé par un autre portefeuille
`insufficient_funds`	402	`wait_and_retry`	Le portefeuille ne dispose pas de suffisamment d'USDC. Rechargez le portefeuille et répétez la même demande tant que l'autorisation est valide.
`quote_expired`	402	`resign`	Le devis a expiré ou a déjà été payé, et votre autorisation a également expiré. Un nouveau devis figure dans la réponse.
`payment_expired`	402	`resign`	L'autorisation a expiré sans avoir été utilisée ou a été annulée. Rien n'a été prélevé. Un nouveau devis figure dans la réponse.
`invalid_request`	400	`abandon`	Champ non valide, champ inconnu, JSON non valide, corps supérieur à 64 KiB ; pays, période, quantité, niveau, forfait ou options non disponibles ; un deuxième forfait résidentiel ; règles spécifiques au point de terminaison
`terms_not_accepted`	400	`resign`	`accept_terms` Les versions ne sont pas à jour. Le corps du texte contient `offer_version` et `privacy_version`
`purpose_not_allowed`	403	`abandon`	`intended_use` n'apparaît pas dans la liste du catalogue
`wallet_rejected`	403	`abandon`	Le portefeuille est bloqué ou figure sur une liste de sanctions
`unauthorized`	401	`abandon`	Non `Authorization: Bearer x402_…` en-tête ; la signature du portefeuille ne correspond pas au défi
`order_not_found`	404	`abandon`	L'ordre n'existe pas, ou le jeton n'est pas valide pour celui-ci
`not_found`	404	`abandon`	La recharge ou le défi n'existe pas, ou le jeton n'est pas valable pour celui-ci
`payment_replayed`	409	`abandon`	Une même autorisation (payeur et nonce) a donné lieu à des contenus différents
`payment_not_settleable`	409	`wait_and_retry`	Le code d'accès n'est plus valide, mais votre autorisation peut toujours être exécutée. Veuillez patienter jusqu'à ce que `authorization_expires_at` avant d'en signer un nouveau
`payment_under_review`	409	`human_required`	Le paiement est en cours d'examen par notre équipe.
`quote_bound_to_other_wallet`	409	`resign`	Un autre portefeuille a déjà utilisé cette citation. Une nouvelle citation figure dans la réponse.
`quote_payment_in_progress`	409	`wait_and_retry`	Un autre paiement correspondant à ce devis est en cours de traitement
`quote_config_mismatch`	409	`abandon`	Le corps de la demande payante ne correspond pas au devis, ou la répétition d'une autorisation de paiement entraîne une nouvelle demande
`idempotency_key_conflict`	409	`abandon`	Votre portefeuille a déjà utilisé cela `idempotency_key` pour un autre paiement au cours des dernières 24 heures
`rate_limited`	429	`wait_and_retry`	Une limite a été dépassée (Contraintes)
`settlement_retry`	503	`retry_same_payment`	Le paiement est toujours en cours de traitement. Répétez la même demande dans `retry_after_seconds`
`channel_paused`	503	`wait_and_retry`	Le service n'accepte temporairement plus de nouveaux paiements
`dependency_unavailable`	503	`wait_and_retry`	Problème temporaire : le prix, le catalogue, la vérification du paiement ou un autre service n'est pas disponible
`internal_error`	500	`wait_and_retry`	Erreur inattendue

Une méthode HTTP incorrecte renvoie 405 avec le code invalid_request.

Chaque réponse du service comporte le X-Request-Id En-tête. Transmettez-le au service d'assistance lorsque vous signalez un problème.

Corps de l'erreur

Réessayer les actions

Codes d'erreur

On this page