Dokumentation / Referenz
Fehlercodes
Der Fehler-Body ist immer gleich aufgebaut. Orientieren Sie sich an code, nicht am Text: Der Text ist für Menschen geschrieben und kann sich ändern.
JSON
{ "error": { "code": "duplicate_order", "message": "Für diese order_id wurde bereits eine Rechnung erstellt" } }Wann eine Wiederholung sicher istBei
429, 500, 503, idempotency_in_progress und Netzwerkfehlern – mit demselben Idempotency-Key: Es entsteht kein Duplikat.Anfrage und Zugriff
| HTTP | code | Ursache und Lösung |
|---|---|---|
| 400 | bad_json, bad_body | Body ist kein JSON, enthält überzählige Felder oder einen Betrag als Zahl statt String – Anfrage korrigieren |
| 400 | bad_idempotency_key | Schlüssel fehlt oder hat ein falsches Format: 8–128 druckbare ASCII-Zeichen, nicht mit d: beginnend |
| 400 | bad_query | Ungültige Listenparameter |
| 401 | unauthorized | Signatur, Zeit, Nonce oder Schlüssel – siehe CP-HMAC |
| 403 | merchant_suspended | Händler gesperrt – wenden Sie sich an den Support |
| 403 | merchant_not_approved | Einrichtung nicht abgeschlossen oder Antrag in Prüfung – schließen Sie den Assistenten im Dashboard ab |
| 403 | billing_suspended | Gebührenrechnung unbezahlt – im Dashboard unter „Abrechnung“ bezahlen; die Sperre wird sofort aufgehoben |
| 404 | not_found | Rechnung existiert nicht oder gehört einem anderen Händler |
| 413 | body_too_large | Body über dem Limit – metadata verkleinern |
| 429 | rate_limited | Zu viele Anfragen – mit exponentiellem Backoff wiederholen |
| 500 | internal | Interner Fehler – mit demselben Idempotency-Key wiederholen |
Rechnungen und Idempotenz
| HTTP | code | Ursache und Lösung |
|---|---|---|
| 409 | duplicate_order | order_id bereits verwendet – eine neue nehmen, z. B. ORDER-1001-2 |
| 409 | idempotency_conflict | Gleicher Schlüssel mit anderem Body |
| 409 | idempotency_in_progress | Die erste Anfrage läuft noch – nach 1–2 s wiederholen |
| 409 | invoice_not_payable | Rechnung abgelaufen oder geschlossen – neue erstellen |
| 422 | invalid_order_id, invalid_price_amount, invalid_price_currency, invalid_return_url, invalid_expires_in_seconds, invalid_metadata | Feld hat die Prüfung nicht bestanden – der Text nennt die Regel |
| 422 | invalid_allowed_assets | Kein Asset aus der Liste ist verfügbar – der Text nennt den Grund für jedes |
| 422 | no_assets | Kein einziges Asset verfügbar – prüfen Sie Wallets und Assets im Dashboard |
| 422 | amount_too_small | Betrag unter dem Minimum aller verfügbaren Assets |
Währungswahl auf der Bezahlseite
Diese Fehler behandelt die Bezahlseite – Ihr Server sieht sie nur, wenn Sie select selbst aufrufen.
| HTTP | code | Ursache |
|---|---|---|
| 409 | asset_locked | Währungswechsel nach einer Zahlung |
| 409 | wallet_not_configured | Kein gültiges Empfangs-Wallet für dieses Netzwerk |
| 409 | wallet_changed, address_conflict | Auswahl wiederholen |
| 422 | asset_not_allowed | Asset nicht in der Rechnung oder nicht mehr zugelassen |
| 503 | rate_unavailable | Kein bestätigter Kurs – bieten Sie einen Stablecoin an |
| 503 | network_unavailable | Empfang in diesem Netzwerk vorübergehend nicht möglich – ein anderes wählen |
Erstattungen
| HTTP | code | Ursache |
|---|---|---|
| 403 | merchant_inactive | Shop gesperrt oder Schlüssel widerrufen |
| 409 | invoice_not_paid | Für die Rechnung wurde kein Asset gewählt – nichts zu erstatten |
| 409 | nothing_to_refund | Alles bereits erstattet oder beantragt |
| 409 | too_many_refunds | 20 offene Anträge für die Rechnung |
| 409 | refund_executor | Die Erstattung führt die Plattform aus, nicht Sie |
| 409 | invoice_status_changed | Rechnungsstatus hat sich nach dem Antrag geändert – mit "ack_status_change": true wiederholen |
| 422 | amount_exceeds_refundable | Betrag höher als verfügbar – verringern oder "full" |
| 422 | invalid_amount, invalid_address, invalid_tx_hash | Feld hat die Prüfung nicht bestanden |