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": {}
}
]
}
}
| Champ | Description |
|---|---|
errorMessage | Code d’erreur lisible par une machine. Utilisez-le dans votre gestion des erreurs. |
errorType | Catégorie de l’erreur : FIELD (un champ n’est pas valide, voir errorField), FORM (la requête dans son ensemble) ou GENERAL. |
errorId | Identifiant de cette erreur. Journalisez-le et indiquez-le dans vos demandes au support. |
errorDescription | Description lisible par un humain. Ne l’utilisez pas dans la logique du programme : le texte peut changer. |
errorField | Le champ de la requête concerné par l’erreur, le cas échéant. |
params | Paramètres supplémentaires de l’erreur, le cas échéant. |
requestParams | Paramè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.
errorMessage | Signification |
|---|---|
missingRequestParameter | Un paramètre obligatoire est absent. |
methodArgumentTypeMismatch | Un paramètre a un type incorrect, par exemple du texte au lieu d’un nombre. |
httpMessageNotReadable | Le corps de la requête n’est pas un JSON valide ou ne correspond pas à la structure attendue. |
unrecognizedField | Le corps de la requête contient un champ que la méthode n’accepte pas. |
badParametersException | Un ou plusieurs paramètres ne sont pas valides. |
badFormatAmountException | Le montant a un format non valide. |
notEnoughMoneyException | Le portefeuille source n’a pas assez de fonds. |
limitPerTransactionException | Le montant dépasse la limite par transaction. |
limitPerMonthException | La transaction dépasse la limite mensuelle. |
walletDoesNotExist | Le portefeuille de la requête n’existe pas. |
walletCurrencyIncorrectException | La devise du portefeuille ne correspond pas à la requête. |
recipientDoesNotExistException | Le compte du destinataire n’existe pas. |
paymentMethodNotAvailableForMerchantApi | Le moyen de paiement n’est pas disponible pour votre API. |
resourceNotFound | L’endpoint n’existe pas. |
attemptsHaveEndedException | Le compte a épuisé sa limite horaire de requêtes. Voir Limite de requêtes. |
tryAgainAfterAWhile | Les données sont temporairement verrouillées. Réessayez plus tard. |
serviceTemporaryUnavailable | Un service est temporairement indisponible. Réessayez plus tard. |
internalServerError | Erreur inattendue du serveur. |
Codes de statut HTTP
| Statut | Signification |
|---|---|
400 | La 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. |
401 | Les en-têtes d’authentification sont absents ou non valides, ou le compte a épuisé sa limite horaire de requêtes (attemptsHaveEndedException). |
404 | L’endpoint demandé est introuvable. |
405 | L’endpoint ne prend pas en charge cette méthode HTTP (httpMethodNotAllowed). |
409 | Les données sont temporairement verrouillées (tryAgainAfterAWhile). |
415 | Le Content-Type de la requête n’est pas pris en charge (unknownContentType). |
500 | Erreur inattendue du serveur (internalServerError). |
503 | Un 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’
errorIdde chaque erreur. - Consultez
errorFieldpour 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 transmettezsciName, Volet.com refuse une deuxième facture avec le mêmeorderIdpour ce Hosted Checkout.
S’il reste impossible de savoir si un paiement a été créé, contactez le support avant de l’envoyer à nouveau.
Voir aussi
- Introduction — URL de base, authentification et format des requêtes
- Statuts — statuts des transactions et des paiements