Fehler
Schlägt eine Anfrage fehl, gibt die API einen HTTP-Fehlerstatus und eine strukturierte Antwort mit einem oder mehreren Fehlern in data.errors zurück.
Fehlerantwort
{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
| Feld | Beschreibung |
|---|---|
errorMessage | Maschinenlesbarer Fehlercode. Verwenden Sie ihn in Ihrer Fehlerbehandlung. |
errorType | Fehlerkategorie: FIELD (ein Feld ist ungültig, siehe errorField), FORM (die Anfrage als Ganzes) oder GENERAL. |
errorId | Kennung dieses Fehlers. Protokollieren Sie sie und geben Sie sie in Anfragen an den Support an. |
errorDescription | Beschreibung für Menschen. Verwenden Sie sie nicht in der Programmlogik: Der Text kann sich ändern. |
errorField | Das Anfragefeld, auf das sich der Fehler bezieht, falls vorhanden. |
params | Zusätzliche Parameter des Fehlers, falls vorhanden. |
requestParams | Anfrageparameter, die mit dem Fehler zusammenhängen, falls vorhanden. |
Häufige Fehlercodes
Die Liste enthält die Codes, die eine Integration in der Regel behandeln muss. Sie ist nicht vollständig: Eine Methode kann auch andere Codes zurückgeben. Behandeln Sie einen unbekannten errorMessage als allgemeinen Fehler und protokollieren Sie seine errorId.
errorMessage | Bedeutung |
|---|---|
missingRequestParameter | Ein Pflichtparameter fehlt. |
methodArgumentTypeMismatch | Ein Parameter hat den falschen Typ, zum Beispiel Text statt einer Zahl. |
httpMessageNotReadable | Der Anfrage-Body ist kein gültiges JSON oder entspricht nicht der erwarteten Struktur. |
unrecognizedField | Der Anfrage-Body enthält ein Feld, das die Methode nicht akzeptiert. |
badParametersException | Ein oder mehrere Parameter sind ungültig. |
badFormatAmountException | Der Betrag hat ein ungültiges Format. |
notEnoughMoneyException | Das Quell-Wallet hat nicht genug Guthaben. |
limitPerTransactionException | Der Betrag überschreitet das Limit pro Transaktion. |
limitPerMonthException | Die Transaktion überschreitet das Monatslimit. |
walletDoesNotExist | Das Wallet in der Anfrage existiert nicht. |
walletCurrencyIncorrectException | Die Währung des Wallets passt nicht zur Anfrage. |
recipientDoesNotExistException | Das Konto des Empfängers existiert nicht. |
paymentMethodNotAvailableForMerchantApi | Die Zahlungsmethode ist für Ihre API nicht verfügbar. |
resourceNotFound | Der Endpunkt existiert nicht. |
attemptsHaveEndedException | Das Konto hat sein stündliches Anfragelimit ausgeschöpft. Siehe Anfragelimit. |
tryAgainAfterAWhile | Die Daten sind vorübergehend gesperrt. Später erneut versuchen. |
serviceTemporaryUnavailable | Ein Dienst ist vorübergehend nicht verfügbar. Später erneut versuchen. |
internalServerError | Unerwarteter Serverfehler. |
HTTP-Statuscodes
| Status | Bedeutung |
|---|---|
400 | Die Anfrage ist fehlerhaft, enthält ungültige Parameter oder kann nicht verarbeitet werden. Wird auch zurückgegeben, wenn eine Bestellung oder ein anderes Objekt nicht gefunden wird. |
401 | Authentifizierungs-Header fehlen oder sind ungültig, oder das Konto hat sein stündliches Anfragelimit ausgeschöpft (attemptsHaveEndedException). |
404 | Der angeforderte Endpunkt wurde nicht gefunden. |
405 | Der Endpunkt unterstützt diese HTTP-Methode nicht (httpMethodNotAllowed). |
409 | Die Daten sind vorübergehend gesperrt (tryAgainAfterAWhile). |
415 | Der Content-Type der Anfrage wird nicht unterstützt (unknownContentType). |
500 | Unerwarteter Serverfehler (internalServerError). |
503 | Ein Dienst ist vorübergehend nicht verfügbar (serviceTemporaryUnavailable). |
Leiten Sie den Fehlercode nicht allein aus dem HTTP-Status ab: Derselbe Status kann unterschiedliche errorMessage-Werte enthalten.
Fehler behandeln
- Protokollieren Sie die
errorIdjedes Fehlers. - Prüfen Sie
errorField, um das zu korrigierende Feld zu finden. - Prüfen Sie nach einem
401den API-Namen, die E-Mail-Adresse des Kontos, den Token und die UTC-Zeit des Servers. - Hat die API keine Berechtigung für den Vorgang oder darf Ihr Server sie nicht aufrufen, prüfen Sie die Berechtigungen der API und ihre IP-Whitelist im Bereich der Zahlungstools.
Sicher wiederholen
Fehler lassen sich in zwei Gruppen einteilen:
- Vorübergehend —
409(tryAgainAfterAWhile),503(serviceTemporaryUnavailable) und Timeouts. Wiederholen Sie Lese- und Validierungsanfragen mit wachsender Pause zwischen den Versuchen. Zu Anfragen, die eine Transaktion oder eine Rechnung erstellen, siehe unten. - Dauerhaft — Authentifizierungs- und Parameterfehler. Korrigieren Sie die Anfrage, statt sie zu wiederholen.
Validierungsanfragen (/api/withdrawal/validation/…) und Abfragen erstellen nichts und können wiederholt werden.
Die Merchant API hat keinen Idempotenzschlüssel. Eine Anfrage, die eine Transaktion oder eine Rechnung erstellt, kann mit einem Timeout oder Fehler enden, nachdem die API sie bereits verarbeitet hat, und eine Wiederholung kann eine zweite erstellen. Prüfen Sie nach einem Timeout oder einem 5xx-Fehler, ob sie erstellt wurde, bevor Sie die Anfrage wiederholen:
- Prüfen Sie bei Auszahlungen den Transaktionsverlauf und den Wallet-Saldo. Siehe Transaktionsverlauf abrufen. Jede Auszahlungsanfrage, die die Validierung besteht, erstellt eine neue Transaktion, auch wenn sie eine frühere wiederholt.
- Suchen Sie bei Rechnungen die Bestellung anhand Ihrer
orderId. Siehe Zahlungsauftrag abrufen. Wenn SiesciNameübergeben, lehnt Volet.com eine zweite Rechnung mit derselbenorderIdfür diesen Hosted Checkout ab.
Ist weiterhin unklar, ob eine Auszahlung erstellt wurde, wenden Sie sich an den Support, bevor Sie sie erneut senden.
Siehe auch
- Einführung — Basis-URL, Authentifizierung und Anfrageformat
- Status — Transaktions- und Zahlungsstatus