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.

Ein Schlüssel pro Aktion

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.

Fehler nach Code lesen

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.
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 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.
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.

Limits

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	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 10.000, Tron 10.000, Solana 10	400 deposit_address_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, davon höchstens 120 nicht GET	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. Das Invoise-Team kann die Rechnungs-, Einzahlungsadress- und Team-Limits für einen 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, pro Dashboard-Sitzung oder pro Client-IP gezählt, wenn nicht authentifiziert. Eine 429-Antwort enthält Retry-After: 60.

Ohne Duplikate wiederholen

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; 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. 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.