Fehler

Die x402-API verwendet echte HTTP-Statuscodes. Jeder Fehler hat denselben JSON-Body, und retry_action sagt Ihrem Agenten, was als Nächstes zu tun ist.

Fehlertext

Name	Typ	Beschreibung
Fehler	String	Fehlercode, siehe Tabelle unten
Nachricht	Zeichenkette	Kurze, für Menschen lesbare Meldung
wiederholbar	Boolesche Werte	Ob Wiederholungen helfen können
retry_action	String	Vorgehensweise: `resign`, `retry_same_payment`, `poll`, `wait_and_retry`, `abandon`, `human_required`
retry_after_seconds	Ganzzahl	Wann erneut versuchen; entspricht dem `Retry-After` Überschrift
Zahlungsstatus	String	`unused`, `in_flight` oder `settled` — ob das Geld entwendet wurde (Wiederholungsversuche und Idempotenz)
authorization_expires_at	String	Bis zu dem Zeitpunkt, zu dem Ihre Vollmacht noch gültig ist; unterzeichnen Sie keine neue, bevor
order_id, operation_id, poll_url	String	Die Reihenfolge und der Vorgang, zu dem die Zahlung gehört, sofern vorhanden
bound_wallet	String	`quote_bound_to_other_wallet`: die Geldbörse, in der das Zitat aufbewahrt wird
Grund_des_Moderators	Zeichenkette	Grund für eine fehlgeschlagene Zahlungsprüfung, aus einer festen Liste, oder `unknown`
Detail	String	Details, zum Beispiel der Pfad des ungültigen Feldes: `/items/0/qty: …`

Antworten mit einem neuen Zitat (quote_expired, payment_expired, quote_bound_to_other_wallet) enthalten außerdem die Anführungszeichen und die PAYMENT-REQUIRED Überschrift.

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

Aktionen wiederholen

retry_action	Was ist zu tun?
`resign`	Tragen Sie die neuen Anforderungen aus dieser Antwort ein (`PAYMENT-REQUIRED`) oder korrigieren Sie die Anfrage
`retry_same_payment`	Senden Sie denselben Auftrag mit denselben `PAYMENT-SIGNATURE`. Erstelle keinen neuen Eintrag
`poll`	In `202` Antworten: Umfrage `poll_url`
`wait_and_retry`	Fangen Sie von vorne an (neues Zitat, neue Signatur), frühestens ab `retry_after_seconds`
`abandon`	Die gleiche Anfrage zu wiederholen, bringt nichts.
`human_required`	Wenden Sie sich an den Support. Unterzeichnen Sie keine neue Vollmacht.

Fehlercodes

Fehler	HTTP	retry_action	Wenn
`payment_required`	402	`resign`	Ein kostenpflichtiger Endpunkt wurde aufgerufen, ohne dass `PAYMENT-SIGNATURE`: Das Zitat steht in der Antwort
`payment_invalid`	402	`abandon`	Der Zahlungsheader ist fehlerhaft oder entspricht nicht der x402-Version 2 (`X-PAYMENT` (einschließlich Version 1); falsches Netzwerk, falscher Asset, falscher Empfänger, falscher Betrag oder falscher Gültigkeitszeitraum; die Signaturprüfung ist fehlgeschlagen; eine Verlängerung oder eine Zahlung, die über eine andere Wallet getätigt wurde
`insufficient_funds`	402	`wait_and_retry`	Das Wallet verfügt nicht über genügend USDC. Laden Sie das Wallet auf und wiederholen Sie die Anfrage, solange die Autorisierung noch gültig ist.
`quote_expired`	402	`resign`	Das Angebot ist abgelaufen oder bereits bezahlt, und Ihre Berechtigung ist ebenfalls abgelaufen. Ein neues Angebot befindet sich in der Antwort.
`payment_expired`	402	`resign`	Die Berechtigung ist ungenutzt abgelaufen oder wurde widerrufen. Es wurde nichts entnommen. In der Antwort befindet sich ein neues Angebot.
`invalid_request`	400	`abandon`	Ungültiges Feld, unbekanntes Feld, ungültiges JSON, Body größer als 64 KiB; Land, Zeitraum, Menge, Stufe, Paket oder Optionen nicht verfügbar; ein zweites Privatkundenpaket; Regeln des jeweiligen Endpunkts
`terms_not_accepted`	400	`resign`	`accept_terms` Die Versionen sind nicht aktuell. Der Hauptteil enthält `offer_version` und `privacy_version`
`purpose_not_allowed`	403	`abandon`	`intended_use` ist nicht in der Katalogliste enthalten
`wallet_rejected`	403	`abandon`	Das Wallet ist gesperrt oder steht auf einer Sanktionsliste
`unauthorized`	401	`abandon`	Nein `Authorization: Bearer x402_…` Kopfzeile; die Wallet-Signatur stimmt nicht mit der Challenge überein
`order_not_found`	404	`abandon`	Der Befehl existiert nicht oder das Token ist dafür ungültig.
`not_found`	404	`abandon`	Das Aufladen oder die Herausforderung existiert nicht, oder das Token ist dafür nicht gültig
`payment_replayed`	409	`abandon`	Die gleiche Autorisierung (Zahler und Nonce) wurde mit unterschiedlichen Inhalten übermittelt
`payment_not_settleable`	409	`wait_and_retry`	Das Zitat ist nicht mehr gültig, aber Ihre Autorisierung kann dennoch ausgeführt werden. Warten Sie, bis `authorization_expires_at` bevor du einen neuen Vertrag unterschreibst
`payment_under_review`	409	`human_required`	Die Zahlung wird derzeit von unseren Mitarbeitern geprüft.
`quote_bound_to_other_wallet`	409	`resign`	Ein anderes Wallet hat dieses Zitat bereits verwendet. Ein neues Zitat ist in der Antwort enthalten.
`quote_payment_in_progress`	409	`wait_and_retry`	Eine weitere Zahlung für dieses Angebot wird derzeit bearbeitet
`quote_config_mismatch`	409	`abandon`	Der Text des bezahlten Auftrags stimmt nicht mit dem Angebot überein, oder eine Wiederholung einer bezahlten Autorisierung führt zu einem weiteren Auftrag
`idempotency_key_conflict`	409	`abandon`	Deine Geldbörse hat dies bereits verwendet `idempotency_key` für eine weitere Zahlung in den letzten 24 Stunden
`rate_limited`	429	`wait_and_retry`	Ein Limit wurde überschritten (Einschränkungen)
`settlement_retry`	503	`retry_same_payment`	Die Zahlung wird noch bearbeitet. Wiederholen Sie die Anfrage in `retry_after_seconds`
`channel_paused`	503	`wait_and_retry`	Der Dienst nimmt vorübergehend keine neuen Zahlungen entgegen.
`dependency_unavailable`	503	`wait_and_retry`	Eine vorübergehende Störung: Der Preis, der Katalog, die Zahlungsprüfung oder ein anderer Dienst ist derzeit nicht verfügbar.
`internal_error`	500	`wait_and_retry`	Unerwarteter Fehler

Eine falsche HTTP-Methode führt zu 405 mit dem Code invalid_request.

Jede Antwort des Dienstes enthält die X-Request-Id Überschrift. Geben Sie diese an den Support weiter, wenn Sie ein Problem melden.

Fehlertext

Aktionen wiederholen

Fehlercodes

On this page