Errori

L’API x402 utilizza codici di stato HTTP reali. Ogni errore ha lo stesso corpo JSON e retry_action indica al tuo agente cosa fare dopo.

Corpo dell'errore

Nome	Tipo	Descrizione
errore	Stringa	Codici di errore: consultare la tabella sottostante
messaggio	Stringa	Breve messaggio di facile comprensione
ripetibile	Booleano	Se la ripetizione può essere d'aiuto
retry_action	Stringa	Cosa fare: `resign`, `retry_same_payment`, `poll`, `wait_and_retry`, `abandon`, `human_required`
retry_after_seconds	Numero intero	Quando riprovare; equivale a `Retry-After` intestazione
payment_state	Stringa	`unused`, `in_flight` oppure `settled` — se i fondi sono stati sottratti (Tentativi e idempotenza)
authorization_expires_at	Stringa	Fino a quando la tua autorizzazione è ancora valida; non firmarne una nuova prima di
order_id, operation_id, poll_url	Stringa	L'ordine e l'operazione a cui si riferisce il pagamento, se presenti
bound_wallet	Stringa	`quote_bound_to_other_wallet`: il portafoglio che contiene la citazione
facilitator_reason	Stringa	Motivo del mancato pagamento, da un elenco prestabilito, oppure `unknown`
dettaglio	Stringa	Dettagli, ad esempio il percorso del campo non valido: `/items/0/qty: …`

Risposte con una nuova citazione (quote_expired, payment_expired, quote_bound_to_other_wallet) contengono anche i campi di citazione e il PAYMENT-REQUIRED intestazione.

{
    "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"
}

Riprova le azioni

retry_action	Cosa fare
`resign`	Firmare i nuovi requisiti indicati in questa risposta (`PAYMENT-REQUIRED`), oppure correggere la richiesta
`retry_same_payment`	Invia la stessa richiesta con lo stesso `PAYMENT-SIGNATURE`. Non crearne uno nuovo
`poll`	In `202` risposte: sondaggio `poll_url`
`wait_and_retry`	Ricominciare da capo (nuova citazione, nuova firma) non prima di `retry_after_seconds`
`abandon`	Ripetere la stessa richiesta non servirà a nulla
`human_required`	Contatta l’assistenza. Non firmare una nuova autorizzazione

Codici di errore

errore	HTTP	retry_action	Quando
`payment_required`	402	`resign`	È stato chiamato un endpoint a pagamento senza `PAYMENT-SIGNATURE`: la citazione è contenuta nella risposta
`payment_invalid`	402	`abandon`	L'intestazione di pagamento è errata o non è conforme allo standard x402 versione 2 (`X-PAYMENT` (inclusa la versione 1); rete, risorsa, destinatario, importo o periodo di validità errati; verifica della firma fallita; un rinnovo o un traffico pagato da un altro portafoglio
`insufficient_funds`	402	`wait_and_retry`	Il portafoglio non dispone di USDC sufficienti. Ricarica il portafoglio e ripeti la stessa richiesta finché l’autorizzazione è valida
`quote_expired`	402	`resign`	Il preventivo è scaduto o è già stato pagato, e anche la tua autorizzazione è scaduta. Nella risposta è presente un nuovo preventivo
`payment_expired`	402	`resign`	L'autorizzazione è scaduta senza essere stata utilizzata oppure è stata annullata. Non è stato prelevato nulla. Nella risposta è presente un nuovo preventivo.
`invalid_request`	400	`abandon`	Campo non valido, campo sconosciuto, JSON non valido, corpo superiore a 64 KiB; paese, periodo, quantità, livello, pacchetto o opzioni non disponibili; un secondo pacchetto residenziale; regole dell’endpoint specifico
`terms_not_accepted`	400	`resign`	`accept_terms` Le versioni non sono aggiornate. Il corpo del testo contiene `offer_version` e `privacy_version`
`purpose_not_allowed`	403	`abandon`	`intended_use` non è presente nell'elenco del catalogo
`wallet_rejected`	403	`abandon`	Il portafoglio è bloccato o presente in un elenco di sanzioni
`unauthorized`	401	`abandon`	No `Authorization: Bearer x402_…` intestazione; la firma del portafoglio non corrisponde alla sfida
`order_not_found`	404	`abandon`	L'ordine non esiste oppure il token non è valido per esso
`not_found`	404	`abandon`	La ricarica o la sfida non esiste, oppure il gettone non è valido per essa
`payment_replayed`	409	`abandon`	La stessa autorizzazione (payer e nonce) è stata accompagnata da contenuti diversi
`payment_not_settleable`	409	`wait_and_retry`	La citazione non è più valida, ma la tua autorizzazione può comunque essere eseguita. Attendi fino a quando `authorization_expires_at` prima di firmarne uno nuovo
`payment_under_review`	409	`human_required`	Il pagamento è attualmente in fase di verifica da parte del nostro staff
`quote_bound_to_other_wallet`	409	`resign`	Un altro portafoglio ha già utilizzato questa citazione. Nella risposta è presente una nuova citazione
`quote_payment_in_progress`	409	`wait_and_retry`	È in corso l’elaborazione di un altro pagamento relativo a questo preventivo
`quote_config_mismatch`	409	`abandon`	Il testo della richiesta a pagamento non corrisponde al preventivo, oppure la ripetizione di un’autorizzazione a pagamento comporta un’altra richiesta
`idempotency_key_conflict`	409	`abandon`	Il tuo portafoglio ha già utilizzato questo `idempotency_key` per un altro pagamento effettuato nelle ultime 24 ore
`rate_limited`	429	`wait_and_retry`	È stato superato un limite (Limiti)
`settlement_retry`	503	`retry_same_payment`	Il pagamento è ancora in fase di elaborazione. Ripeti la stessa richiesta in `retry_after_seconds`
`channel_paused`	503	`wait_and_retry`	Il servizio non accetta temporaneamente nuovi pagamenti
`dependency_unavailable`	503	`wait_and_retry`	Un errore temporaneo: il prezzo, il catalogo, la verifica del pagamento o un altro servizio non sono disponibili
`internal_error`	500	`wait_and_retry`	Errore imprevisto

Un metodo HTTP errato restituisce 405 con il codice invalid_request.

Ogni risposta del servizio contiene il X-Request-Id intestazione. Forniscila al servizio di assistenza quando segnali un problema.

Corpo dell'errore

Riprova le azioni

Codici di errore

On this page