Codes d'erreur

​

Vue d’ensemble

• Un code d’état HTTP indiquant la catégorie générale de l’erreur
• Un code d’erreur spécifique qui identifie la nature exacte de l’erreur
• Un message d’erreur lisible par l’homme expliquant ce qui s’est mal passé
• Des détails supplémentaires sur l’erreur lorsque cela est applicable

• Déboguer les problèmes d’intégration
• Mettre en œuvre une gestion appropriée des erreurs dans votre application
• Fournir des retours significatifs aux utilisateurs finaux
• Maintenir un système de traitement des paiements robuste

​

Codes d’erreur API standard

​

Format de réponse d’erreur

{
  "code": "UNSUPPORTED_COUNTRY",
  "message": "Country AI currently not supported"
}

​

Référence des codes d’erreur

​

Authentification & Compte

• UNAUTHORIZED
  • Déclencheur : Pas de clé API ou jeton/scope invalide
  • Message : Vous n’êtes pas autorisé à effectuer cette action
• MERCHANT_NOT_LIVE
  • Déclencheur : Entreprise toujours en mode test/sandbox
  • Message : Le commerçant n’est pas en ligne

​

Paiements & Check-out

• CHECKOUT_SESSION_CONSUMED
  • Déclencheur : La session de paiement a déjà généré un paiement
  • Message : La session de paiement a déjà été consommée
• NO_ELIGIBLE_PAYMENT_METHODS
  • Déclencheur : Après filtrage, rien ne reste
  • Message : Aucune méthode de paiement éligible trouvée
• PAYMENT_NOT_SUCCEEDED
  • Déclencheur : Tentative de remboursement/traitement d’un paiement non réussi
  • Message : Le paiement fourni n’a pas réussi
• PREVIOUS_PAYMENT_PENDING
  • Déclencheur : Tentative de création d’une charge alors que la précédente est dans un état non terminal
  • Message : Impossible de créer une nouvelle charge car le paiement précédent n’est pas encore réussi
• UNSUCCESSFUL_PAYMENT_ID
  • Déclencheur : L’ID de paiement référence un paiement non réussi
  • Message : L’ID de paiement a un statut non réussi.

​

Connecteurs & BYOP

• BYOP_CONNECTOR_DISABLED
  • Déclencheur : Mise à jour d’une méthode de paiement sur un abonnement routé via un connecteur BYOP désactivé
  • Message : L’abonnement est routé via le connecteur (BYOP) du commerçant qui est actuellement désactivé
• BYOP_CUSTOM_INVOICE_ADDRESS_MISSING
  • Déclencheur : Un paiement routé par le commerçant (BYOP) manque de l’adresse de facture personnalisée requise
  • Message : L’adresse de facture personnalisée BYOP est requise lorsqu’un paiement est routé via le connecteur du commerçant
• CONNECTOR_LABEL_ALREADY_EXISTS
  • Déclencheur : Création d’un connecteur avec une étiquette qui existe déjà
  • Message : Un connecteur avec cette étiquette existe déjà. Veuillez choisir une étiquette différente.

​

Remboursements

• EXISTING_REFUND_REQUEST_PROCESSING
  • Déclencheur : La demande de remboursement précédente est toujours en cours de traitement
  • Message : Une demande de remboursement avec le statut « Pending » est toujours en cours de traitement
• LINE_ITEM_FULLY_REFUNDED
  • Déclencheur : Tentative de remboursement d’un élément de ligne déjà entièrement remboursé
  • Message : L’article a déjà été entièrement remboursé et ne peut être remboursé davantage.
• LINE_ITEM_NOT_FOUND
  • Déclencheur : ID d’élément ne faisant pas partie du paiement référencé
  • Message : L’article n’a pas été trouvé dans le paiement
• LINE_ITEM_PRORATED
  • Déclencheur : Remboursement ou mise à jour tentée sur une ligne au prorata
  • Message : L’article ne peut être remboursé car il est proratisé
• LINE_ITEM_REFUND_AMOUNT_TOO_HIGH
  • Déclencheur : Montant du remboursement > montant payé (taxe incl.)
  • Message : Le montant demandé pour le remboursement de l’article , y compris la taxe, est , supérieur au montant payé
• LINE_ITEM_REFUND_AMOUNT_TOO_LOW
  • Déclencheur : Montant du remboursement en dessous du seuil minimum
  • Message : Le montant demandé pour le remboursement de l’article est , ce qui est trop bas
• NOTHING_TO_REFUND
  • Déclencheur : Aucun montant remboursable restant; tous les articles de ligne positifs déjà entièrement remboursés
  • Message : Aucun montant remboursable restant. Tous les articles de ligne positifs ont été entièrement remboursés.
• PARTIAL_REFUND_NOT_ALLOWED
  • Déclencheur : Remboursement partiel tenté sur une méthode de paiement qui ne prend en charge que les remboursements complets
  • Message : Les remboursements partiels ne sont pas autorisés pour cette méthode de paiement
• PAYMENT_ALREADY_REFUNDED
  • Déclencheur : Remboursement en double
  • Message : Ce paiement a déjà été remboursé
• PAYMENT_HAS_BEEN_REFUNDED
  • Déclencheur : Le paiement a été entièrement remboursé
  • Message : L’ID de paiement a été entièrement remboursé.
• REFUND_AMOUNT_EXCEEDS_PAID_AMOUNT
  • Déclencheur : Montant total du remboursement > montant payé
  • Message : Le montant du remboursement calculé est supérieur au montant payé
• REFUND_WINDOW_EXPIRED
  • Déclencheur : Hors fenêtre de remboursement autorisée
  • Message : Les remboursements ne peuvent pas être initiés jours après la création du paiement. Contactez support@dodopayments.com.
• ZERO_AMOUNT_PAYMENT_REFUND_NOT_ALLOWED
  • Déclencheur : Tentative de remboursement d’un paiement de montant nul
  • Message : Impossible de rembourser un paiement dont le montant de la devise est nul

​

Abonnements & Extensions

• ADDONS_IN_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Déclencheur : Tentative d’ajout d’addons aux abonnements basés sur l’utilisation
  • Message : Les addons dans les abonnements ne sont pas pris en charge pour la facturation basée sur l’utilisation
• ADDONS_NOT_ALLOWED_FOR_ON_DEMAND
  • Déclencheur : Tentative d’ajout d’addons aux abonnements à la demande
  • Message : Les addons ne sont pas autorisés pour les abonnements à la demande
• CANCEL_SCHEDULED_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Déclencheur : Le portail client tente d’annuler un changement de plan prévu alors que l’entreprise a désactivé cette action
  • Message : L’annulation du changement de plan prévu est désactivée pour le portail client.
• CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Déclencheur : Tentative de facturation d’un abonnement programmé pour annulation
  • Message : Abonnement programmé pour annulation
• CUSTOMER_HAS_EXISTING_SUBSCRIPTION
  • Déclencheur : Création d’un abonnement pour un client qui en a déjà un, lorsque plusieurs abonnements par client ne sont pas autorisés
  • Message : Le client a déjà un abonnement existant. Pour autoriser plusieurs abonnements par client, changez les paramètres de l’entreprise
• DO_NOT_BILL_NOT_ALLOWED_IN_CUSTOMER_PORTAL
  • Déclencheur : Mode prorata do_not_bill utilisé dans un changement de plan du Portail Client
  • Message : Le mode prorata do_not_bill n’est pas autorisé dans le portail client
• DUPLICATE_ADDON_IDS_IN_REQUEST
  • Déclencheur : Le même addon_id apparaît plus d’une fois dans la requête
  • Message : Les identifiants d’addons en double ne sont pas autorisés
• INACTIVE_SUBSCRIPTION_PLAN_CHANGE_NOT_SUPPORTED
  • Déclencheur : Changement de plan sur un abonnement inactif
  • Message : Le changement de plan n’est pas pris en charge pour les abonnements inactifs
• INVALID_PRORATION_MODE_WITH_NEXT_BILLING_DATE
  • Déclencheur : Un mode de proration autre que full_immediately utilisé avec effective_at: next_billing_date
  • Message : Seul le mode de proration full_immediately est autorisé avec effective_at: next_billing_date
• MISSING_ADDON_IDS
  • Déclencheur : Liste addon_id vide ou identifiants inconnus
  • Message : Un ou plusieurs identifiants de produit n’existent pas :
• ON_DEMAND_PLAN_CHANGE_NOT_SUPPORTED
  • Déclencheur : Échange de plan non autorisé pour à la demande
  • Message : Le changement de plan n’est pas pris en charge pour les abonnements à la demande
• ON_DEMAND_USAGE_BASED_BILLING_NOT_SUPPORTED
  • Déclencheur : Tentative d’utilisation sur demande avec facturation basée sur l’utilisation
  • Message : Les abonnements à la demande ne sont pas pris en charge pour la facturation basée sur l’utilisation
• ONE_TIME_PRODUCTS_NOT_ALLOWED_FOR_ON_DEMAND
  • Déclencheur : Produit unique ajouté à un abonnement à la demande
  • Message : Les produits uniques ne sont pas autorisés pour les abonnements à la demande
• PENDING_PLAN_CHANGE_EXISTS
  • Déclencheur : Un nouveau changement de plan demandé alors qu’un précédent est toujours en attente de paiement
  • Message : Un changement de plan en attente existe déjà pour cet abonnement. Veuillez attendre que le paiement actuel soit terminé.
• PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Déclencheur : Modification de plan via le Portail Client alors que l’entreprise l’a désactivé
  • Message : Le changement de plan d’abonnement pour le portail client est désactivé.
• PLAN_CHANGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION
  • Déclencheur : Changement de plan tenté sur un abonnement programmé pour l’annulation
  • Message : Abonnement programmé pour l’annulation
• SCHEDULE_PLAN_CHANGE_FOR_CUSTOMER_PORTAL_DISABLED
  • Déclencheur : Planification d’un changement de plan via le Portail Client alors que l’entreprise l’a désactivé
  • Message : La planification des changements de plan est désactivée pour cette entreprise.
• SCHEDULED_PLAN_CHANGE_EXISTS
  • Déclencheur : Création d’un changement de plan programmé alors qu’il en existe déjà un
  • Message : Un changement de plan programmé existe déjà pour cet abonnement. Veuillez annuler le changement programmé existant avant d’en créer un nouveau.
• SCHEDULED_PLAN_CHANGE_NOT_FOUND
  • Déclencheur : Référencement ou annulation d’un changement de plan programmé inexistant
  • Message : Aucun changement de plan programmé trouvé pour cet abonnement.
• SUBSCRIPTION_EXPIRED
  • Déclencheur : Facturation après ends_at
  • Message : L’abonnement a expiré, impossible de créer de nouvelles charges
• SUBSCRIPTION_INACTIVE
  • Déclencheur : Statut ≠ ACTIVE
  • Message : L’abonnement n’est pas actif
• SUBSCRIPTION_NOT_ON_DEMAND
  • Déclencheur : Attendu à la demande mais obtenu intervalle fixe
  • Message : L’abonnement n’est déjà pas à la demande
• SUBSCRIPTION_PAYMENT_RETRY_LIMIT_EXCEEDED
  • Déclencheur : Les tentatives de paiement de l’abonnement ont dépassé le nombre maximal de tentatives
  • Message : Limite maximale de 10 tentatives de réessai dépassée pour cet abonnement

​

Produits, Panier & Marques

• BRAND_MISMATCH
  • Déclencheur : Les articles du panier appartiennent à différentes marques
  • Message : Tous les articles du panier produit doivent appartenir à la même marque
• BRAND_NOT_ENABLED
  • Déclencheur : La marque est désactivée ou non active
  • Message : La marque fournie n’est pas activée
• BRAND_SUBMISSION_NOT_ENABLED
  • Déclencheur : Fonction de resoumission de vérification de marque non activée
  • Message : La resoumission de vérification de marque n’est pas activée
• FILE_IN_USE
  • Déclencheur : Suppression d’un fichier de produit numérique encore référencé par des subventions de droits actifs (passer ?force=true pour ignorer)
  • Message : Le fichier numérique est référencé par des subventions actives
• INVALID_SUGGESTED_PRICE
  • Déclencheur : Le prix PWYW < prix minimum autorisé
  • Message : Le prix suggéré ne peut pas être inférieur au prix minimum. Dans le cas de pay what you want, le prix est considéré comme le montant minimum accepté
• LOCALIZED_PRICE_ALREADY_EXISTS
  • Déclencheur : Un prix localisé existe déjà pour ce produit et pays/devise
  • Message : Un prix localisé pour ce produit et ce pays/devise existe déjà
• LOCALIZED_PRICE_DUPLICATES_BASE
  • Déclencheur : Le prix localisé duplique la devise/pays de base du produit
  • Message : Le prix localisé duplique la devise/pays de base du produit
• LOCALIZED_PRICE_SHAPE_MISMATCH
  • Déclencheur : La forme de prix localisé ne correspond pas à pricing_mode du produit
  • Message : La forme de prix localisé ne correspond pas au mode de tarification du produit
• MISSING_PRODUCT_INFORMATION
  • Déclencheur : Le produit existe mais des informations obligatoires sont manquantes
  • Message : Le produit existe mais d’autres informations obligatoires sont manquantes ou invalides
• PAY_AS_YOU_WANT_AMOUNT_REQUIRED
  • Déclencheur : Prix manquant pour produit PWYW
  • Message : Le montant est obligatoire pour le produit à payer comme vous voulez
• PRODUCT_CART_EMTPY
  • Déclencheur : Panier produit vide soumis
  • Message : product_cart est vide (le code d’erreur est intentionnellement orthographié EMTPY pour correspondre à la valeur exacte que renvoie l’API)
• PRODUCT_COLLECTION_IS_DELETED
  • Déclencheur : Opération sur une collection de produits qui a été supprimée
  • Message : Aucun message
• PRODUCT_COLLECTION_MUST_HAVE_PRODUCTS
  • Déclencheur : Suppression du dernier produit (ou dernier groupe avec produits) d’une collection
  • Message : Impossible de supprimer le dernier produit d’une collection. Archivez plutôt la collection.
• PRODUCT_IS_DELETED
  • Déclencheur : Produit supprimé en douceur
  • Message : Aucun message
• PRODUCT_PRICING_MODE_REQUIRED
  • Déclencheur : Ajout de prix localisés avant que pricing_mode du produit ne soit défini
  • Message : Le mode de tarification du produit doit être défini avant l’ajout de prix localisés
• SLUG_ALREADY_TAKEN
  • Déclencheur : Le slug/URL courte du produit demandé est déjà utilisé
  • Message : Le slug est déjà pris
• UNABLE_TO_EDIT_PRIMARY_BRAND
  • Déclencheur : Tentative de mise à jour de la marque principale via l’API régulière
  • Message : La marque principale ne peut pas être mise à jour via ce point de terminaison de l’API.

​

Réductions

• DISCOUNT_ALREADY_USED_ON_SUBSCRIPTION
  • Déclencheur : Réapplication d’une réduction déjà utilisée sur cet abonnement
  • Message : Cette remise a déjà été utilisée sur cet abonnement
• DISCOUNT_CODE_ALREADY_EXISTS
  • Déclencheur : Création de code de réduction en double
  • Message : Le code de réduction existe déjà
• DISCOUNT_CODE_EXPIRED
  • Déclencheur : Code de réduction passé sa date expires_at
  • Message : Le code de réduction a expiré
• DISCOUNT_CODE_USAGE_LIMIT_EXCEEDED
  • Déclencheur : Réutilisation de la réduction après usage_limit atteint
  • Message : La limite d’utilisation ne peut être inférieure au nombre de fois utilisé / Le code de réduction a atteint la limite d’utilisation
• DISCOUNT_NOT_APPLICABLE_TO_NEW_PRODUCT
  • Déclencheur : Changement de plan vers un produit auquel la réduction existante ne s’applique pas
  • Message : La réduction n’est pas applicable au produit du nouveau plan
• DISCOUNT_NOT_AVAILABLE_FOR_ON_DEMAND
  • Déclencheur : Code appliqué à l’abonnement à la demande
  • Message : Le coupon de réduction n’est pas disponible pour les abonnements à la demande
• DISCOUNT_NOT_AVAILABLE_FOR_PRODUCT
  • Déclencheur : Code appliqué à des produits non liés
  • Message : Le coupon de réduction n’est pas disponible pour ce produit
• INVALID_DISCOUNT_CODE
  • Déclencheur : Code inexistant / non applicable
  • Message : Code de réduction invalide / Le code de réduction ne peut être appliqué à aucun produit du panier
• INVALID_PERCENTAGE
  • Déclencheur : Montant en pourcentage > 100% (ou 10,000 points de base)
  • Message : Le montant en pourcentage ne peut pas être supérieur à 10000 / Le montant du code de réduction ne peut être supérieur à 100%
• UNSUPPORTED_DISCOUNT_TYPE
  • Déclencheur : Réductions à montant fixe, etc., pas encore en ligne
  • Message : Seuls les codes de réduction en pourcentage sont pris en charge pour l’instant

​

Clés de licence

• ACTIVATION_LIMIT_LESS_THAN_CURRENT_AMOUNT
  • Déclencheur : Activations de clé de licence : nouvelle limite < nombre d’instances existant
  • Message : La nouvelle limite d’activation ne peut être inférieure au nombre d’instances actuel
• INACTIVE_LICENSE_KEY
  • Déclencheur : Statut de la clé ≠ ACTIVE
  • Message : La clé de licence n’est pas active
• LICENSE_KEY_LIMIT_REACHED
  • Déclencheur : Activations = limite
  • Message : Limite d’activation de la clé de licence atteinte
• LICENSE_KEY_NOT_FOUND
  • Déclencheur : ID d’instance ou ID de clé invalide
  • Message : L’instance de clé de licence n’a pas été trouvée ou n’appartient pas à cette clé de licence
• NO_EXPIRY_ON_SUBSCRIPTION_LICENSE_KEYS
  • Déclencheur : Tentative de définir la date d’expiration d’une clé à base d’abonnement
  • Message : Impossible de définir une date d’expiration pour une clé de licence basée sur l’abonnement

​

Facturation basée sur l’utilisation & Compteurs

• DUPLICATE_METER_IDS_IN_REQUEST
  • Déclencheur : Le même ID de compteur apparaît plusieurs fois dans la demande
  • Message : Les identifiants de compteurs en double ne sont pas autorisés
• INVALID_QUANTITY
  • Déclencheur : Quantité invalide spécifiée pour la tarification basée sur l’utilisation
  • Message : Une seule quantité autorisée pour les produits à prix basé sur l’utilisation
• METER_IS_DELETED
  • Déclencheur : Tentative d’utilisation d’un compteur supprimé
  • Message : Le compteur a déjà été supprimé
• MISSING_METER_IDS
  • Déclencheur : Liste d’ID de compteur vide ou contenant des ID invalides
  • Message : Un ou plusieurs identifiants de compteur n’existent pas :

​

Facturation basée sur le crédit

• CREDIT_ENTITLEMENT_IS_DELETED
  • Déclencheur : Opération sur un droit de crédit qui a été supprimé
  • Message : Le droit de crédit a déjà été supprimé
• CREDIT_ENTITLEMENT_NAME_ALREADY_EXISTS
  • Déclencheur : Création d’un droit de crédit avec un nom qui existe déjà
  • Message : Un droit de crédit avec ce nom existe déjà
• OVERAGE_LIMIT_EXCEEDED
  • Déclencheur : Une utilisation ou une déduction de crédit dépasserait la limite de dépassement configurée
  • Message : Limite de dépassement dépassée

​

Portefeuille

• INSUFFICIENT_WALLET_FUNDS
  • Déclencheur : Solde du portefeuille < montant du débit
  • Message : Fonds insuffisants dans le portefeuille
• NEGATIVE_BALANCE_ADJUSTMENT
  • Déclencheur : Tentative de rendre le solde du portefeuille négatif
  • Message : Le solde du portefeuille ne peut pas être rendu négatif

​

Devise, Taxe & Région

• EXCHANGE_RATE_NOT_FOUND
  • Déclencheur : Pas de taux de change pour la paire de devises from → to
  • Message : Taux de change introuvable pour convertir de Devise à Devise
• INVALID_TAX_ID
  • Déclencheur : Validation VAT/GST/TIN échouée
  • Message : Le numéro d’identification fiscale est invalide
• REQUEST_AMOUNT_BELOW_MINIMUM
  • Déclencheur : Montant < minimum du produit
  • Message : Le montant ne peut pas être inférieur au montant minimum spécifié pour le produit
• TOTAL_PAYMENT_AMOUNT_BELOW_MINIMUM_AMOUNT
  • Déclencheur : Total combiné du panier < minimum du portail
  • Message : Un montant minimum de est requis pour traiter le paiement
• UNSUPPORTED_BILLING_CURRENCY
  • Déclencheur : Abonnements limités à l’USD
  • Message : La facturation en devises non USD n’est pas prise en charge pour les abonnements
• UNSUPPORTED_COUNTRY
  • Déclencheur : Géolocalisation non encore prise en charge
  • Message : Le pays n’est pas encore pris en charge
• UNSUPPORTED_CURRENCY
  • Déclencheur : Devise du produit ou de l’addon invalide
  • Message : La devise n’est pas prise en charge actuellement / Seuls les produits USD et INR sont actuellement pris en charge / Seuls les USD et INR sont pris en charge pour le prix addon / Ne peut demander que l’USD ou l’INR pour la devis_facturation / Devise non prise en charge / Devise inattendue pour les abonnements carte indien
• UNSUPPORTED_TAX_CATEGORY
  • Déclencheur : Chaîne de catégorie fiscale non dans l’énumération
  • Message : Catégorie non prise en charge actuellement

​

Validation & Requêtes

• DUPLICATE_LINE_ITEMS_IN_REQUEST
  • Déclencheur : Le même item_id apparaît deux fois dans items[]
  • Message : Identifiants d’items en double spécifiés dans le tableau des items
• INVALID_QUERY_PARAMS
  • Déclencheur : Paramètres de requête mutuellement exclusifs / malformés
  • Message : Les paramètres de requête doivent contenir uniquement soit time_frame soit (start, end)
• INVALID_REQUEST_BODY
  • Déclencheur : JSON malformé ou violation de schéma
  • Message : Le corps de votre requête est invalide. Veuillez vérifier vos en-têtes de requête et l’objet.
• INVALID_REQUEST_PARAMETERS
  • Déclencheur : Sémantique incorrecte (par ex. date antérieure)
  • Message : Impossible de changer next_billing_date à une date passée
• MAXIMUM_KEYS_REACHED
  • Déclencheur : Métadonnées / champs personnalisés dépassant 50 paires
  • Message : Dépasse 50 paires clé-valeur

​

Général & Système

• INTEGER_CONVERSION_FAILURE
  • Déclencheur : Toute conversion entier ↔ string/decimal échouant côté serveur
  • Message : Échec de la conversion d’entier
• INTERNAL_SERVER_ERROR
  • Déclencheur : Exceptions non captées ; vous devriez enregistrer les détails côté serveur
  • Message : Aucun message public (générique 500)
• NOT_FOUND
  • Déclencheur : 404 générique pour toute ressource manquante
  • Message : Élément non trouvé (ou plus spécifique)
• TOO_MANY_REQUESTS
  • Déclencheur : Limitation de débit 429
  • Message : Aucun message
• UNSUPPORTED_ACTION
  • Déclencheur : Action non prise en charge pour le type de ressource
  • Message : La modification des plans pour les abonnements basés sur l’utilisation n’est pas prise en charge

​

Meilleures Pratiques

1. Gérez toujours les erreurs avec élégance dans votre application
2. Implémentez une journalisation appropriée des erreurs
3. Utilisez des messages d’erreur appropriés pour les utilisateurs finaux
4. Mettez en place une logique de réessai pour les erreurs transitoires
5. Contactez le support pour les problèmes non résolus

​

Support