Nie wiederholen
invalid_request, invalid_amount, unknown_asset_or_rail, asset_not_offered, unauthorized. Die Anfrage ist fehlerhaft: Eine unveränderte Wiederholung führt zum gleichen Ergebnis. Beheben Sie sie oder zeigen Sie den Grund an.
Developers
Fehlerkatalog
Jeder Fehler trägt einen stabilen, maschinenlesbaren Code und einen kohärenten HTTP-Status. Der Code ist das, worauf Ihre Integration verzweigen sollte: Der Text kann sich ändern, der Code nicht.
Form eines Fehlers
Die aktuelle Form ist bewusst minimal. Sie ist stabil, und das ist entscheidend: ein Code und nichts, das ein internes Detail preisgibt.
{ "error": "rate_stale" }{
"error": "rail_not_open",
"reason": {
"fr": "La retenue TDS de 1 % et l’enregistrement FIU-IND exigent une entite locale…",
"en": "The 1% TDS withholding and FIU-IND registration require a local entity…"
}
}Manche Fehler enthalten ein zweisprachiges Grund-Objekt, das dem Benutzer unverändert angezeigt werden soll. Ein geschlossener Zahlungsweg ist einer: Der Grund erklärt eine benannte regulatorische Einschränkung, keinen Ausfall, und das Anzeigen spart eine Support-Anfrage. Die versionierte API wird diesem Umschlag eine Anfrage-ID hinzufügen, damit Sie uns auf eine genaue Zeile in unseren Protokollen verweisen können.
Gültige Codes
Diese Codes werden heute vom Kurs-Endpunkt zurückgegeben.
| code | HTTP | Was es bedeutet | Was zu tun ist |
|---|---|---|---|
invalid_request | 400 | Der Anfragetext besteht die Schema-Validierung nicht: fehlendes Feld, falscher Typ, Wert außerhalb der zulässigen Grenzen. | Stellen Sie sicher, dass der Betrag ein String und keine Zahl ist und dass die Richtung genau „sell“ oder „receive“ ist. |
invalid_amount | 400 | Der Betrag kann nicht geparst werden oder hat mehr Dezimalstellen, als der Vermögenswert oder die Währung akzeptiert. | Auf die Einheitenpräzision kürzen: 6 Dezimalstellen für USDT, 8 für BTC, 2 für den Euro, 0 für den CFA-Franc. |
unknown_asset_or_rail | 404 | Die Kennung des Vermögenswerts oder Zahlungswegs existiert nicht im Katalog. | Kennungen sind stabil und werden nie neu vergeben. Laden Sie den Katalog neu, anstatt sie zu erraten. |
rail_not_open | 409 | Der Zahlungsweg existiert, ist aber nicht offen. Die Antwort enthält den genauen Grund in beiden Sprachen. | Zeigen Sie den Grund unverändert an: Er erklärt eine regulatorische Einschränkung, keinen Ausfall. Bieten Sie einen offenen Zahlungsweg im selben Land an. |
asset_not_offered | 409 | Der Vermögenswert ist im Katalog, wird aber nicht angeboten – der Fall für Vermögenswerte mit erhöhter Anonymität. | Bieten Sie ihn in Ihrem Auswahlfeld nicht an. Der Katalog gibt ihn mit seinem Grund zurück, damit Sie ihn erklären können. |
rate_stale | 503 | Der letzte bekannte Preis überschreitet das maximal tolerierte Alter. Die Engine weigert sich, ein Angebot zu erstellen, anstatt einen veralteten Preis als verbindlich zu dienen. | Wiederholen Sie den Versuch nach einigen Sekunden. Speichern Sie nicht das letzte erfolgreiche Angebot zwischen, um die Lücke zu füllen: Das wäre genau der Fehler, den dieser Code verhindert. |
rate_unavailable | 503 | Für dieses Paar aus Vermögenswert und Währung ist kein Preis verfügbar. | Deaktivieren Sie das Paar in Ihrer Oberfläche, anstatt einen Schätzwert anzuzeigen. Ein angezeigter Schätzwert wird zu einer Erwartung. |
quote_failed | 500 | Unerwarteter Fehler während der Berechnung. Es wird kein Angebot zurückgegeben. | Wiederholen Sie den Versuch einmal; wenn der Fehler weiterhin besteht, schreiben Sie uns mit dem genauen Zeitstempel des Aufrufs. |
Codes aus dem veröffentlichten Vertrag
Diese Codes begleiten Endpunkte, die noch nicht geöffnet sind. Sie werden veröffentlicht, damit Ihre Fehlerbehandlung nur einmal geschrieben wird.
| code | HTTP | Was es bedeutet | Was zu tun ist |
|---|---|---|---|
unauthorized | 401 | Schlüssel fehlt, widerrufen oder in der falschen Umgebung verwendet. | Ein sk_test_-Schlüssel funktioniert nicht in der Produktion, und umgekehrt auch nicht: Das ist beabsichtigt. |
idempotency_conflict | 409 | Derselbe Idempotenzschlüssel wurde bereits mit einem anderen Anfragetext verwendet. | Ein Schlüssel gehört zu einer Absicht. Wenn sich der Inhalt ändert, ändert sich der Schlüssel; andernfalls ist nicht zu unterscheiden, welche der beiden Bestellungen erneut ausgeführt werden soll. |
quote_expired | 409 | Das Angebot hat sein Sperrfenster überschritten. | Fragen Sie erneut ein Angebot an und lassen Sie den neuen Betrag akzeptieren. Wir passen den Preis niemals stillschweigend gegen den Kunden an. |
beneficiary_rejected | 422 | Die Empfängerdaten bestehen die Zahlungsweg-Validierung nicht: ungültige Prüfsumme, nicht konformes Format oder ein Name, der nicht mit der verifizierten Identität übereinstimmt. | Die Antwort nennt das fehlerhafte Feld. Der Name des Begünstigten muss der verifizierten Identität entsprechen: Eine Auszahlung an Dritte ist nicht möglich. |
country_not_served | 451 | Das Zielland wird nicht bedient: Sanktionen, restriktive Maßnahmen oder das Fehlen eines lokalen Rahmens. | Der Code 451 wird bewusst anstelle einer 404 gewählt: Wenn wir ablehnen, sagen wir, dass es eine Ablehnung ist und warum. |
rate_limited | 429 | Zu viele Aufrufe innerhalb des gleitenden Zeitfensters. | Beachten Sie den Retry-After-Header. Angebote sind günstig in der Warteschlange, teuer im Daueraufruf. |
not_found | 404 | Die Ressource existiert nicht oder gehört nicht zu Ihrem Schlüssel. | Beide Fälle geben denselben Code zurück: Eine Antwort, die sie unterscheidet, würde es jedem ermöglichen, die Referenzen anderer aufzulisten. |
Was kein Fehler ist
Ein Betrag außerhalb der Grenzen des Zahlungswegs gibt ein gültiges Angebot mit einem limitError-Objekt zurück. Es ist kein Fehler: Es sind Informationen, die Ihre Oberfläche anzeigen sollte.
"limitError": { "code": "below_min", "limit": "20.00" }Diesen Fall als HTTP-Fehler zu behandeln, würde Sie um den berechneten Betrag bringen und damit um die Fähigkeit, dem Benutzer zu sagen: „Sie sind 16,53 EUR unter dem Minimum für diese Auszahlungsmethode.“ Die Grenze gilt für den Nettobetrag, den der Empfänger erhält.
Wiederholen oder nicht
Drei Familien, drei Verhaltensweisen. Das Wiederholen eines Validierungsfehlers in einer Schleife füllt nur Ihre Protokolle.
Mit Backoff wiederholen
rate_stale, rate_unavailable, quote_failed und jede Ratenbegrenzung. Warten Sie einige Sekunden, mit wachsendem Abstand zwischen den Versuchen. Füllen Sie die Wartezeit nicht mit einem zwischengespeicherten Kurs.
Eine Entscheidung anfordern
rail_not_open, quote_expired, beneficiary_rejected, country_not_served. Die Situation erfordert eine menschliche Entscheidung: Bieten Sie einen anderen Zahlungsweg, ein neues Angebot, korrigierte Details an.