Zum Hauptinhalt springen

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": {}
}
]
}
}
FeldBeschreibung
errorMessageMaschinenlesbarer Fehlercode. Verwenden Sie ihn in Ihrer Fehlerbehandlung.
errorTypeFehlerkategorie: FIELD (ein Feld ist ungültig, siehe errorField), FORM (die Anfrage als Ganzes) oder GENERAL.
errorIdKennung dieses Fehlers. Protokollieren Sie sie und geben Sie sie in Anfragen an den Support an.
errorDescriptionBeschreibung für Menschen. Verwenden Sie sie nicht in der Programmlogik: Der Text kann sich ändern.
errorFieldDas Anfragefeld, auf das sich der Fehler bezieht, falls vorhanden.
paramsZusätzliche Parameter des Fehlers, falls vorhanden.
requestParamsAnfrageparameter, 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.

errorMessageBedeutung
missingRequestParameterEin Pflichtparameter fehlt.
methodArgumentTypeMismatchEin Parameter hat den falschen Typ, zum Beispiel Text statt einer Zahl.
httpMessageNotReadableDer Anfrage-Body ist kein gültiges JSON oder entspricht nicht der erwarteten Struktur.
unrecognizedFieldDer Anfrage-Body enthält ein Feld, das die Methode nicht akzeptiert.
badParametersExceptionEin oder mehrere Parameter sind ungültig.
badFormatAmountExceptionDer Betrag hat ein ungültiges Format.
notEnoughMoneyExceptionDas Quell-Wallet hat nicht genug Guthaben.
limitPerTransactionExceptionDer Betrag überschreitet das Limit pro Transaktion.
limitPerMonthExceptionDie Transaktion überschreitet das Monatslimit.
walletDoesNotExistDas Wallet in der Anfrage existiert nicht.
walletCurrencyIncorrectExceptionDie Währung des Wallets passt nicht zur Anfrage.
recipientDoesNotExistExceptionDas Konto des Empfängers existiert nicht.
paymentMethodNotAvailableForMerchantApiDie Zahlungsmethode ist für Ihre API nicht verfügbar.
resourceNotFoundDer Endpunkt existiert nicht.
attemptsHaveEndedExceptionDas Konto hat sein stündliches Anfragelimit ausgeschöpft. Siehe Anfragelimit.
tryAgainAfterAWhileDie Daten sind vorübergehend gesperrt. Später erneut versuchen.
serviceTemporaryUnavailableEin Dienst ist vorübergehend nicht verfügbar. Später erneut versuchen.
internalServerErrorUnerwarteter Serverfehler.

HTTP-Statuscodes​

StatusBedeutung
400Die 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.
401Authentifizierungs-Header fehlen oder sind ungültig, oder das Konto hat sein stündliches Anfragelimit ausgeschöpft (attemptsHaveEndedException).
404Der angeforderte Endpunkt wurde nicht gefunden.
405Der Endpunkt unterstützt diese HTTP-Methode nicht (httpMethodNotAllowed).
409Die Daten sind vorübergehend gesperrt (tryAgainAfterAWhile).
415Der Content-Type der Anfrage wird nicht unterstützt (unknownContentType).
500Unerwarteter Serverfehler (internalServerError).
503Ein 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 errorId jedes Fehlers.
  • Prüfen Sie errorField, um das zu korrigierende Feld zu finden.
  • Prüfen Sie nach einem 401 den 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 Sie sciName übergeben, lehnt Volet.com eine zweite Rechnung mit derselben orderId für diesen Hosted Checkout ab.

Ist weiterhin unklar, ob eine Auszahlung erstellt wurde, wenden Sie sich an den Support, bevor Sie sie erneut senden.

  • Einführung — Basis-URL, Authentifizierung und Anfrageformat
  • Status — Transaktions- und Zahlungsstatus