Fehlercodes

Ein einziger Umschlag für alle Fehlschläge:

{ "error": { "code": "invalid_request", "message": "…" } }

HTTP	code	Wann	Was tun
401	missing_api_key	Kein Authorization: Bearer sk_… und kein X-API-Key	Schlüssel ergänzen
401	invalid_api_key	Schlüssel widerrufen, unbekannt, oder Konto inaktiv	Schlüssel und Kontostatus prüfen
403	insufficient_scope	Der Schlüssel hat dieses Recht nicht (etwa auszahlen)	Schlüssel mit passendem Geltungsbereich ausgeben
403	client_inactive	Das Konto ist nicht geprüft oder gesperrt	KYB-Unterlagen abschließen
403	not_live	Konto noch nicht für den Echtbetrieb freigegeben	Vorerst einen sk_test_-Schlüssel verwenden
404	not_found	Ressource existiert nicht — oder gehört Ihnen nicht	Kennung prüfen
409	already_exists	Duplikat (Referenz bereits verwendet)	Bestehende Ressource lesen
409	precondition_failed	Der Zustand lässt die Operation nicht zu	Ressource ansehen, Reihenfolge korrigieren
409	concurrent_request	Gleicher Idempotency-Key, anderer Inhalt	Einen Schlüssel nicht für zwei Operationen verwenden
422	invalid_request	Ungültiger Inhalt (Feld, Betrag, Asset)	Die message nennt das fehlerhafte Feld
422	insufficient_funds	Guthaben reicht für diese Auszahlung nicht	GET /v1/balances prüfen
429	—	300 Anfragen/Minute überschritten	Den Retry-After-Header einhalten
502	upstream_error	Eine Abhängigkeit ist ausgefallen	Mit demselben Idempotency-Key wiederholen
503	temporarily_unavailable	Vorübergehend nicht verfügbar	Mit Backoff wiederholen

Gefahrlos wiederholen

502 und 503 werden immer mit demselben Idempotency-Key wiederholt: war die erste Anfrage serverseitig durchgegangen, erhalten Sie ihr Ergebnis, statt ein Duplikat zu erzeugen.

Ein 502 heißt nicht, dass nichts passiert ist. Es sagt, dass eine Abhängigkeit nicht geantwortet hat, nicht, dass die Operation nicht existiert. Genau dafür gibt es Idempotenz: wiederholen, nicht neu anlegen.

not_found bei einer Ressource, die existiert

Die API antwortet 404 auch, wenn die Ressource einem anderen Händler gehört: schließen Sie aus einem 404 nie auf die Existenz einer Ressource.

Ein abgelehnter Inhalt ist kein ignoriertes Feld

Ein unbekanntes Feld in einem JSON-Body wird stillschweigend ignoriert, nicht abgelehnt. Ein Tippfehler im Namen eines optionalen Feldes erzeugt also keinen Fehler: er erzeugt eine Operation ohne das, was Sie gesendet zu haben glaubten. Lesen Sie die Namen in der Referenz nach, statt sich auf das Ausbleiben eines 422 zu verlassen.