Aller au contenu principal

Erreurs

Lorsqu’une requête échoue, l’API renvoie un statut HTTP d’erreur et une réponse structurée avec une ou plusieurs erreurs dans data.errors.

Réponse d’erreur​

{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
ChampDescription
errorMessageCode d’erreur lisible par une machine. Utilisez-le dans votre gestion des erreurs.
errorTypeCatégorie de l’erreur : FIELD (un champ n’est pas valide, voir errorField), FORM (la requête dans son ensemble) ou GENERAL.
errorIdIdentifiant de cette erreur. Journalisez-le et indiquez-le dans vos demandes au support.
errorDescriptionDescription lisible par un humain. Ne l’utilisez pas dans la logique du programme : le texte peut changer.
errorFieldLe champ de la requête concerné par l’erreur, le cas échéant.
paramsParamètres supplémentaires de l’erreur, le cas échéant.
requestParamsParamètres de la requête liés à l’erreur, le cas échéant.

Codes d’erreur courants​

La liste ci-dessous couvre les codes qu’une intégration doit généralement gérer. Elle n’est pas complète : une méthode peut renvoyer d’autres codes. Traitez un errorMessage inconnu comme une erreur générale et journalisez son errorId.

errorMessageSignification
missingRequestParameterUn paramètre obligatoire est absent.
methodArgumentTypeMismatchUn paramètre a un type incorrect, par exemple du texte au lieu d’un nombre.
httpMessageNotReadableLe corps de la requête n’est pas un JSON valide ou ne correspond pas à la structure attendue.
unrecognizedFieldLe corps de la requête contient un champ que la méthode n’accepte pas.
badParametersExceptionUn ou plusieurs paramètres ne sont pas valides.
badFormatAmountExceptionLe montant a un format non valide.
notEnoughMoneyExceptionLe portefeuille source n’a pas assez de fonds.
limitPerTransactionExceptionLe montant dépasse la limite par transaction.
limitPerMonthExceptionLa transaction dépasse la limite mensuelle.
walletDoesNotExistLe portefeuille de la requête n’existe pas.
walletCurrencyIncorrectExceptionLa devise du portefeuille ne correspond pas à la requête.
recipientDoesNotExistExceptionLe compte du destinataire n’existe pas.
paymentMethodNotAvailableForMerchantApiLe moyen de paiement n’est pas disponible pour votre API.
resourceNotFoundL’endpoint n’existe pas.
attemptsHaveEndedExceptionLe compte a épuisé sa limite horaire de requêtes. Voir Limite de requêtes.
tryAgainAfterAWhileLes données sont temporairement verrouillées. Réessayez plus tard.
serviceTemporaryUnavailableUn service est temporairement indisponible. Réessayez plus tard.
internalServerErrorErreur inattendue du serveur.

Codes de statut HTTP​

StatutSignification
400La requête est mal formée, contient des paramètres non valides ou ne peut pas être traitée. Également renvoyé lorsqu’une commande ou une autre entité est introuvable.
401Les en-têtes d’authentification sont absents ou non valides, ou le compte a épuisé sa limite horaire de requêtes (attemptsHaveEndedException).
404L’endpoint demandé est introuvable.
405L’endpoint ne prend pas en charge cette méthode HTTP (httpMethodNotAllowed).
409Les données sont temporairement verrouillées (tryAgainAfterAWhile).
415Le Content-Type de la requête n’est pas pris en charge (unknownContentType).
500Erreur inattendue du serveur (internalServerError).
503Un service est temporairement indisponible (serviceTemporaryUnavailable).

Ne déduisez pas le code d’erreur du seul statut HTTP : un même statut peut porter différentes valeurs de errorMessage.

Gérer les erreurs​

  • Journalisez l’errorId de chaque erreur.
  • Consultez errorField pour trouver le champ à corriger.
  • Après un 401, vérifiez le nom de l’API, l’adresse e-mail du compte, le jeton et l’heure UTC du serveur.
  • Si l’API n’a pas l’autorisation pour l’opération ou si votre serveur n’a pas le droit de l’appeler, vérifiez les autorisations de l’API et sa liste blanche IP dans la section des outils de paiement.

Relancer sans risque​

Les erreurs se répartissent en deux groupes :

  • Temporaires — 409 (tryAgainAfterAWhile), 503 (serviceTemporaryUnavailable) et les délais d’attente dépassés. Relancez les requêtes de lecture et de validation en allongeant le délai entre les tentatives. Pour les requêtes qui créent une transaction ou une facture, voir ci-dessous.
  • Permanentes — erreurs d’authentification et de paramètres. Corrigez la requête au lieu de la répéter.

Les requêtes de validation (/api/withdrawal/validation/…) et les recherches ne créent rien et peuvent être répétées.

La Merchant API n’a pas de clé d’idempotence. Une requête qui crée une transaction ou une facture peut dépasser le délai d’attente ou échouer alors que l’API l’a déjà traitée, et la répéter peut en créer une seconde. Après un délai d’attente dépassé ou une erreur 5xx, vérifiez si elle a été créée avant de la répéter :

  • Pour les paiements, vérifiez l’historique des transactions et le solde du portefeuille. Voir Récupération de l’historique des transactions. Chaque requête de paiement qui passe la validation crée une nouvelle transaction, même si elle répète une requête précédente.
  • Pour les factures, recherchez la commande par votre orderId. Voir Récupération d’une commande de paiement. Si vous transmettez sciName, Volet.com refuse une deuxième facture avec le même orderId pour ce Hosted Checkout.

S’il reste impossible de savoir si un paiement a été créé, contactez le support avant de l’envoyer à nouveau.

  • Introduction — URL de base, authentification et format des requêtes
  • Statuts — statuts des transactions et des paiements