Gestion des erreurs

Format d'erreur standard

Toutes les réponses d'erreur suivent ce format :

{
  "success": false,
  "error": {
    "message": "Description lisible de l'erreur",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123def456..."
  }
}

Champ	Description
`message`	Description de l'erreur en anglais
`code`	Code d'erreur interne (voir tableau ci-dessous)
`statusCode`	Code HTTP de la réponse
`traceId`	Identifiant unique pour le support technique

Note de sécurité : Les erreurs internes du serveur (5xx) renvoient un message générique ("An error has occurred...") pour ne pas exposer les détails d'implémentation. Le traceId permet à l'équipe support d'enquêter sur l'erreur concrète.

Note sur les environnements : Les codes d'erreur, formats et messages sont identiques dans les environnements Live et Test. Il n'y a pas de différence dans la gestion des erreurs entre environnements.

Catalogue des codes d'erreur

Erreurs d'authentification et d'autorisation (11xxx)

Code	HTTP	Description	Action recommandée
11001	403	Clé API invalide ou non fournie	Vérifiez l'en-tête `X-API-KEY`
11002	403	IP non autorisée	Configurez votre IP dans le tableau de bord (Intégrations > API Keys)
11008	403	Accès refusé à la ressource	Le webcode ne correspond pas, le paiement n'appartient pas à l'API externe, ou erreur d'environnement

Erreurs de validation (12xxx)

Code	HTTP	Description	Action recommandée
12001	400	Paramètre requis manquant ou format invalide	Vérifiez les champs obligatoires et leurs formats
12002	400	Date au format incorrect	Utilisez le format ISO 8601 (ex. : `2026-07-15T14:00:00Z`)
12006	400	Format de pays invalide	Utilisez ISO 3166-1 alpha-2 (ex. : `ES`, `FR`, `DE`)
12009	400	Pays non pris en charge	Contactez le support pour la liste des pays disponibles

Erreurs de ressource (10xxx)

Code	HTTP	Description	Action recommandée
10404	404	Ressource introuvable	Vérifiez que le `sessionId` ou `paymentReference` est correct

Erreurs POS (13xxx)

Code	HTTP	Description	Action recommandée
13001	500	Erreur du fournisseur de paiement	Réessayez après quelques secondes. Si cela persiste, contactez le support
13004	502	Erreur de communication avec le terminal	Vérifiez que le terminal est allumé et connecté
13005	409	Terminal occupé	Attendez la fin de la transaction en cours et réessayez

Conflits d'idempotence (409)

Ces conflits n'ont pas de code numérique interne : le message permet de les distinguer du 409 de terminal occupé (13005).

Cas	HTTP	Message (littéral)	Action recommandée
Même `Idempotency-Key`, body différent	409	`Idempotency key reused with a different request body.`	Utilisez une nouvelle clé ou renvoyez le même body que la requête d'origine
Même `Idempotency-Key`, autre endpoint	409	`Idempotency key already used for a different endpoint.`	Ne réutilisez pas la même clé entre des endpoints distincts

Erreurs internes (99xxx)

Code	HTTP	Description	Action recommandée
99001	500	Erreur interne du serveur	Notez le `traceId` et contactez le support

Exemple de réponse d'erreur

{
  "success": false,
  "error": {
    "message": "External device is busy.",
    "code": 13005,
    "statusCode": 409,
    "traceId": "b2f3d36dc305249e8d1ebaa49ef616f1"
  }
}

Bonnes pratiques

Nouvelles tentatives

Erreurs 4xx : ne réessayez pas (le problème est dans la requête)
Erreurs 5xx : réessayez avec un backoff exponentiel (1 s, 2 s, 4 s, 8 s…)
409 : si c'est 13005 (terminal occupé), attendez 5 à 10 secondes et réessayez. Si le message commence par Idempotency key…, ne réessayez pas à l'aveugle : corrigez la clé ou le body de la requête
Utilisez toujours Idempotency-Key pour que les nouvelles tentatives soient sûres (mais assurez-vous de ne pas la réutiliser avec un body différent)

Journalisation

Enregistrez le traceId des réponses d'erreur pour faciliter la communication avec le support technique.

Validation préalable

Validez les données avant d'envoyer la requête pour éviter les erreurs 400 :

amount.value doit être un entier positif (centimes)
amount.currency doit être exactement 3 lettres majuscules (EUR, GBP ou USD)
webcode ne peut pas être vide
Les URLs (urlOk, urlKo) doivent être des URLs valides avec protocole
reason pour les remboursements doit être l'une des 5 valeurs exactes autorisées

Documentation développeurs