Zum Inhalt springen

Idempotenz, Fehler und Limits

Wenn eine Anfrage einem Timeout unterliegt, wissen Sie nicht, ob sie erfolgreich war. Wiederholen Sie denselben Vorgang mit demselben Idempotency-Key, um eine zweite Zahlung zu vermeiden.

  1. Erzeugen Sie vor der ersten Anfrage einen eindeutigen Schlüssel und speichern Sie ihn mit Ihrer Bestellung.
  2. Senden Sie ihn in Idempotency-Key beim Erstellen oder Ändern einer Geschäftsressource.
  3. Wiederholen Sie nach einem Timeout dieselbe Methode, denselben Pfad und denselben Body mit diesem Schlüssel.
  4. Erstellen Sie für eine neue Aktion einen neuen Schlüssel.

Der Schlüssel muss nicht leer und höchstens 128 Byte lang sein. Das Wiederholen einer abgeschlossenen Aktion gibt deren gespeicherte Antwort zurück. Das Ändern des Bodys unter demselben Schlüssel gibt 409 idempotency_conflict zurück.

Dies gilt für Geschäftsmutationen wie Rechnungen, Shops, Schlüssel und Webhooks. Lesende GET-Aufrufe und Anmelde-Challenges verwenden diesen Mechanismus nicht. Befolgen Sie die Anforderungen jedes Endpunkts.

external_id hilft, eine Zahlung mit Ihrer Bestellung zu verknüpfen; es ist kein Idempotenzschlüssel.

Beispiel:

{"error":{"code":"idempotency_conflict","message":"idempotency_conflict"}}

Verwenden Sie error.code in Ihrem Programm. Schließen Sie nicht vom Antwortkörper auf Erfolg, ohne zuvor den HTTP-Status zu prüfen.

Code Nächster Schritt
unauthorized Prüfen Sie die Zugangsdaten, Berechtigungen und etwaige IP-Beschränkungen. Melden Sie sich erneut an, wenn die Sitzung abgelaufen ist.
mfa_required Schließen Sie den zweiten Faktor des Kontos mit dessen Sitzung ab.
onboarding_required Schließen Sie /onboarding ab, bevor Sie Shop-Vorgänge durchführen.
idempotency_key_required Geben Sie einen gespeicherten, nicht leeren Schlüssel mit höchstens 128 Byte an.
idempotency_conflict Finden Sie die ursprüngliche Anfrage. Erstellen Sie nicht stillschweigend eine neue Zahlung.
json_content_type_required / invalid_json Senden Sie Content-Type: application/json und nur dokumentierte Felder.
unsupported_network / unsupported_asset Wählen Sie ein unterstütztes Netzwerk und einen unterstützten Token.
network_not_ready / asset_not_ready Warten Sie auf Verfügbarkeit oder wählen Sie eine andere einsatzbereite Route.
address_unavailable 503: Die Adresse konnte gerade nicht abgeleitet werden. Wiederholen Sie dieselbe Anfrage mit demselben Idempotency-Key.
amount_below_minimum / fee_exceeds_amount Prüfen Sie Betrag, Dezimalstellen und Shop-Bedingungen.
shop_archived / shop_not_found Prüfen Sie den Shop und den Zugriff.
invalid_expires_in Senden Sie 1h, 2h, 1d, 7d, 30d, 180d oder 365d, und nur beim Erstellen einer Rechnung. Einzahlungen laufen nicht ab.
invalid_assets / issuance_in_group Senden Sie eindeutige {chain_id, token}-Paare ohne chain_id und token; stornieren oder pausieren Sie eine Gruppe über deren eigene id. Siehe mehrere Token oder Netzwerke.
solana_setup_required / tron_setup_required Legen Sie zuerst den Solana- oder Tron-Empfänger des Shops fest.
invoice_amount_limit / sandbox_amount_limit Senken Sie den Betrag auf das Limit.
active_invoice_limit_reached / deposit_address_limit_reached Stornieren Sie nicht mehr benötigte Rechnungen oder deaktivieren Sie Einzahlungen, oder bitten Sie Invoise, das Limit zu erhöhen.
api_key_limit_reached / too_many_allowed_ips / webhook_limit_reached Widerrufen Sie nicht verwendete Schlüssel, kürzen Sie die IP-Liste oder verwenden Sie einen vorhandenen Endpunkt weiter.
team_limit_reached Entfernen Sie ein Mitglied oder widerrufen Sie eine ausstehende Einladung, oder bitten Sie Invoise, das Limit zu erhöhen.
shop_limit_reached Archivieren Sie einen Shop, den Sie nicht mehr nutzen, oder bitten Sie Invoise, das Limit zu erhöhen.
own_merchant / last_merchant_owner / wallet_in_use Einen selbst angelegten Händler oder einen, dessen letzter Inhaber Sie sind, können Sie nicht verlassen; leiten Sie zuerst die Auszahlungen der genannten Shops von Ihrer Wallet weg.
account_disabled Das Invoise-Team hat das Konto gesperrt; der Grund steht in error.details. Siehe gesperrte Konten.
rate_limited Warten Sie die in Retry-After angegebene Anzahl Sekunden, bevor Sie es erneut versuchen.

Wenn eine Anfrage ein Limit überschreiten würde, lehnt Invoise sie mit dem üblichen Fehlerkörper und dem untenstehenden Code ab.

Limit Wert Fehler
Betrag einer Rechnung standardmäßig 1.000.000 Token 400 invoice_amount_limit
Betrag einer Sandbox-Rechnung oder eines simulierten Transfers 10.000 Token 400 sandbox_amount_limit
Aktive Rechnungen pro Händler 2.000 400 active_invoice_limit_reached
Aktive Einzahlungsadressen pro Händler, pro Netzwerkfamilie EVM 100.000, Tron 100.000, Solana 100 400 deposit_address_limit_reached
Neue Zahlungsadressen pro Händler und Stunde: Rechnungen, Einzahlungen und jede ihrer Optionen das Limit aktiver Rechnungen des Händlers, standardmäßig 2.000 429 rate_limited
Aktive Shops pro Händler 10 400 shop_limit_reached
Nicht widerrufene API-Schlüssel pro Shop 10 400 api_key_limit_reached
Zulässige IP-Adressen oder CIDR-Bereiche pro Schlüssel 10 400 too_many_allowed_ips
Webhook-Endpunkte pro Shop 10 400 webhook_limit_reached
Teammitglieder und ausstehende Einladungen pro Händler 10 400 team_limit_reached
Anfragen pro Minute 1.200 pro Zugangsdaten, davon höchstens 120 nicht GET; 3.000 und 300 pro Client-IP 429 rate_limited

Betragslimits sind in ganzen Token, nicht in Basiseinheiten. Jeder unterstützte Token ist ein Dollar-Stablecoin, sodass 1.000.000 Token etwa 1.000.000 $ entsprechen.

Eine Rechnung ist aktiv, bis sie bezahlt, storniert oder abgelaufen ist. Eine in mehreren Netzwerken angebotene Rechnung zählt einmal. Eine Einzahlungsadresse ist aktiv, bis sie deaktiviert wird; jede Netzwerkoption einer Einzahlung ist eine separate Adresse. Sandbox und Produktion werden für beide Limits getrennt gezählt. Ein archivierter Shop zählt nicht zum Shop-Limit.

Die Werte oben sind Standardwerte. Das Invoise-Team kann für einen Händler andere Rechnungs-, Einzahlungsadress-, Shop- und Team-Limits festlegen, Ihre können also abweichen, und die Betragsgrenze für alle Händler ändern.

Das Team-Limit gilt sowohl beim Einladen als auch beim Annehmen einer Einladung. Die URL eines Webhook-Endpunkts kann geändert werden, sodass Sie einen Endpunkt weiterverwenden können, statt einen weiteren hinzuzufügen.

Anfragen werden pro API-Schlüssel oder Dashboard-Sitzung gezählt und immer zusätzlich pro Client-IP, sodass erfundene Zugangsdaten keine neue Zählung beginnen.

Jede 429-Antwort enthält Retry-After, die Anzahl der Sekunden, die Sie warten sollen. Beim Anfragelimit pro Minute ist es 60. Stündliche Limits, etwa das Budget für neue Adressen, E-Mail-Anmeldecodes und Wallet-Challenges, nennen die Sekunden, bis ihr Fenster wieder öffnet, also bis zu einer Stunde.

Wiederholen Sie Timeouts und vorübergehende Serverfehler mit demselben Schlüssel, mit zunehmenden Verzögerungen. Warten Sie bei 429 die in Retry-After angegebenen Sekunden ab (beim Budget für neue Adressen bis zu einer Stunde); senden Sie nicht sofort weitere Anfragen. Beheben Sie ungültige Eingaben und Zugriffsfehler, bevor Sie es erneut versuchen.

Für Webhooks wiederholt Invoise die Zustellung bis zu 72 Stunden lang; siehe Wiederholungen. Nehmen Sie das Ereignis dauerhaft an, geben Sie 2xx zurück und verarbeiten Sie es dann. Deduplizieren Sie anhand von Invoise-Event-ID.

Ältere /projects-Routen sind Aliase von /shops, einschließlich ihres Idempotenzbereichs. Verwenden Sie /shops für neue Integrationen. Ältere Fehlernamen können project_* verwenden.