Erreurs API fréquentes
La liste complète des codes est dans la référence des erreurs. Ici, les cas qui reviennent le plus, et comment les corriger.
Toutes les erreurs ont la même forme : un message lisible (dans la langue du header x-lang), un errorCode au format STATUT:CODE (par exemple 404:MODEL_NOT_FOUND), le path appelé et la date.
Le n° 1 : du JSON envoyé à un endpoint multipart
Les créations et mises à jour qui acceptent une image attendent du multipart/form-data :
| Endpoint | Content-Type |
|---|---|
POST/coupons, POST/events, POST/transits, POST/hotels | multipart/form-data |
PATCH/store-cards, PATCH/wallets, PATCH/clients/{id}/specific | multipart/form-data |
POST/communications, POST/csv-operations/import-csv | multipart/form-data |
| Clients, passes, notifications, trajets | application/json |
Erreurs associées : INVALID_MULTIPART (boundary absent ou mal formé), UNSUPPORTED_MEDIA_TYPE (415), FILE_REQUIRED (image obligatoire absente).
Trois règles en multipart :
- Laissez l’outil écrire le header. Avec
curl -Fou unFormDataJavaScript, leContent-Typeet sonboundarysont ajoutés pour vous. Un header écrit à la main, sans boundary, fait échouer la requête. - Objets imbriqués en chaîne JSON.
colors,security,locations,displayOptions,iosHeader,date: un champ de formulaire contenant du JSON. - Booléens en texte :
"true"/"false". Images PNG ou JPEG, de 1 Ko à 5 Mo.
- curl
- SDK Node.js
- nodejs
- php
- python
- java
- csharp
- go
- ruby
- CURL
curl -L 'https://api-v2.test.eldowallet.fr/coupons' \
-H 'Accept: application/json' \
-H 'x-lang: fr' \
-H 'Authorization: Bearer <token>' \
-F 'strip=@"strip.png"' \
-F 'name="Bienvenue"' \
-F 'description="-10 % sur votre prochain achat"' \
-F 'barcodeFormat="QR_CODE"' \
-F 'isWelcomeCoupon="true"' \
-F 'colors="{\"backgroundColor\":\"\#59358B\",\"foregroundColor\":\"\#FFFFFF\",\"labelColor\":\"\#F2FBCE\"}"'
401 : non authentifié
- Header
Authorization: Bearer $ELDO_TOKENabsent ou mal formé :UNAUTHORIZED. - Jeton expiré : reconnectez-vous (POST
/auth/login), ou utilisez un jeton de wallet pour les intégrations serveur (POST/wallets/tokens). Voir Authentification.
403 : accès refusé
Vous êtes authentifié, mais la ressource ne vous appartient pas (template ou client d’un autre wallet), ou votre rôle ne suffit pas : FORBIDDEN.
Un client d’un autre wallet renvoie CLIENT_DOES_NOT_BELONG_TO_THIS_WALLET.
404 : introuvable
MODEL_NOT_FOUND: identifiant inexistant. Les identifiants sont des ObjectId : 24 caractères hexadécimaux.PATH_NOT_FOUND: URL inconnue. Vérifiez l'URL de base (https://api-v2.test.eldowallet.fren test, voir Environnements) et le chemin.PASS_NOT_FOUND: le code-barres scanné ne correspond à aucun pass de ce template.STORECARD_NOT_FOUND: la carte de fidélité du wallet n’est pas encore configurée (PATCH/store-cards).
409 : conflit
EMAIL_ALREADY_EXISTS,CLIENT_ALREADY_EXISTS: ce client existe déjà dans le wallet. Mettez-le à jour au lieu de le recréer.BARCODE_ALREADY_EXISTS: ce code-barres est déjà attribué.OVERLAPPING_DATES: la chambre d’hôtel est déjà réservée sur ces dates.PUSH_NOTIFICATION_SCHEDULE_CONFLICT: une notification est déjà planifiée trop près de cette date.STORE_CARD_ALREADY_EXISTS: un wallet n’a qu’une carte de fidélité. Modifiez-la avec PATCH/store-cards.
400 : requête invalide
VALIDATION_ERROR,MISSING_REQUIRED_FIELDS: champ obligatoire manquant ou valeur hors liste. Le détail liste les champs en cause.UNEXPECTED_FIELD: un champ inconnu a été envoyé. Vérifiez l’orthographe, par exemplebarcodeFormat(coupon, transport) etbarcodeType(événement, carte de fidélité).INVALID_JSON: corps JSON mal formé.PASS_ALREADY_REDEEMED: second POST/passes/template/{templateId}/redeem/{barcode}sur le même pass. Si le premier scan était une erreur, annulez avec POST/passes/template/{templateId}/unredeem/{barcode}.PASS_NOT_REDEEMED: POST/passes/template/{templateId}/unredeem/{barcode}sur un pass jamais validé.SYNC_EXECUTION_NOT_ALLOWED:forceSync: truesur une opération en masse de 1 000 éléments ou plus.
5xx : erreur serveur ou service externe
500(UNKNOWN_ERROR) : réessayez. Si l’erreur persiste, contactez le support avec lepath, ladateet le corps envoyé.502: le fournisseur SMS a échoué (SMS_SEND_FAILED…). Réessayez plus tard.503(PASS_BUILDER_ERROR) : le service qui génère les passes est indisponible. Réessayez plus tard.