Skip to Content
Codes d'erreur

Codes d’erreur

Toutes les erreurs de l’API ont la même forme :

Réponse d'erreur
{ "error": "message lisible, susceptible d'évoluer", "code": "CODE_MACHINE_STABLE" }

Programmez contre code, jamais contre error. Certains codes ajoutent des champs, indiqués ci-dessous. Les codes propres à un endpoint sont aussi listés sur sa page de référence.

400 — Requête invalide

codeCauseQue faire
INVALID_BODYCorps absent ou JSON invalideEnvoyer un JSON valide avec Content-Type: application/json
VALIDATION_ERRORChamp manquant ou invalide (transactions, webhooks)Corriger la requête
INVALID_AMOUNTMontant nul, négatif ou non entierEnvoyer un entier XAF > 0
INVALID_CURRENCYDevise autre que XAFXAF
INVALID_OPERATOROpérateur inconnuAIRTEL ou MOOV
REFERENCE_REQUIRED, INVALID_REFERENCERéférence absente ou trop longueFournir votre identifiant de commande
INVALID_TTLttl_minutes hors 1–60Ajuster la durée
INVALID_RETURN_URLreturn_url absente du format attendu : adresse https absolue, sans identifiants, 2048 caractères au plus (http://localhost seulement avec une clé de test)Corriger l’adresse de retour
INVALID_IDIdentifiant qui n’est pas un UUIDVérifier l’identifiant
CUSTOMER_PHONE_REQUIREDPaiement live sans téléphone du payeurFournir customer_phone
PAYMENT_SESSION_AMOUNT_TOO_LOW, PAYMENT_SESSION_AMOUNT_TOO_HIGH, TRANSACTION_AMOUNT_TOO_LOW, TRANSACTION_AMOUNT_TOO_HIGHMontant hors des bornes de votre compteAjuster le montant ; les bornes se consultent dans le dashboard
WEBHOOK_URL_UNSAFEURL de webhook non publique ou non HTTPS pour le liveUtiliser une URL publique en HTTPS
INVALID_STATUS, INVALID_DATE_FROM, INVALID_DATE_TO, INVALID_DATE_RANGE, INVALID_SEARCHFiltre de liste invalideCorriger le filtre

401 — Non authentifié

codeCauseQue faire
API_KEY_MISSINGEn-tête X-API-Key absentAjouter l’en-tête
API_KEY_INVALID_FORMATLa clé ne commence ni par kadryza_live_ ni par kadryza_test_Vérifier la variable d’environnement
API_KEY_UNAUTHORIZEDClé inconnue ou révoquéeGénérer une nouvelle clé dans le dashboard

403 — Non autorisé

codeCauseQue faire
EMAIL_NOT_VERIFIEDL’e-mail du compte n’est pas vérifiéValider l’e-mail depuis le lien reçu
KYC_REQUIREDProfil marchand incompletCompléter le profil dans le dashboard
API_KEY_PERMISSION_DENIEDLa clé n’a pas la portée requiseUtiliser une clé avec la bonne portée
LIVE_MODE_NOT_ALLOWEDClé live, mais le mode live n’est pas activé pour le compteTerminer la checklist go-live
PAYMENT_SESSION_DAILY_LIMIT_EXCEEDED, DAILY_TRANSACTION_LIMIT_EXCEEDEDPlafond journalier atteintRéessayer le lendemain (UTC) ou demander un ajustement

404 — Introuvable

codeCause
NOT_FOUNDRessource inconnue, ou appartenant à un autre compte ou à l’autre environnement (une clé de test ne voit pas les objets live)

409 — Conflit

codeCauseQue faire
DUPLICATE_REFERENCEreference déjà utilisée dans cet environnementRelire l’objet existant (GET /v1/payment-sessions/by-reference)
IDEMPOTENCY_CONFLICTMême référence de Hosted Checkout avec un contenu différentUtiliser une nouvelle référence
NOT_CANCELLABLESession live, ou session qui n’est plus AWAITING_PAYMENTNe pas annuler ; suivre le statut
OPERATOR_NO_LONGER_AVAILABLE, OPERATOR_SELECTION_CONFLICT, CHECKOUT_CANCELLED, CHECKOUT_NOT_CANCELLABLEPage de paiement hébergée (détails)—

410 — Expiré

codeCause
CHECKOUT_EXPIREDHosted Checkout expiré avant le choix de l’opérateur

429 — Trop de requêtes

codeChamps ajoutésQue faire
RATE_LIMIT_EXCEEDEDretry_after_seconds (et en-tête Retry-After)Attendre le délai indiqué avant de réessayer

501 — Non implémenté

codeCause
PROVIDER_NOT_IMPLEMENTEDAucun fournisseur implémenté pour cet opérateur

502 — Passerelle

codeCause
WEBHOOK_TEST_FAILEDVotre endpoint n’a pas répondu 2xx à POST /v1/webhooks/:id/test

503 — Service indisponible

codeChamps ajoutésCauseQue faire
PROVIDER_RAIL_NOT_READYoperator, environment, failed_checksRéseau d’encaissement de l’opérateur indisponible en liveProposer l’autre opérateur ou réessayer plus tard
NO_COLLECTION_NUMBER_AVAILABLE—Aucun numéro disponible pour cet opérateurIdem
PROVIDER_UNAVAILABLE—Aucun fournisseur actif pour cet opérateurIdem
OPERATOR_AVAILABILITY_UNAVAILABLE—Disponibilité des opérateurs invérifiable momentanémentRéessayer
LEGACY_LIVE_TRANSACTION_DISABLED—Création de transaction ou paiement par lien avec une clé liveUtiliser les Payment Sessions
RATE_LIMIT_UNAVAILABLE—Contrôle de débit momentanément indisponible sur une opération sensibleRéessayer avec un délai

500 — Erreur interne

codeQue faire
INTERNAL_ERRORRéessayer avec un délai. Pour une création, relire d’abord par référence : la première tentative a pu aboutir.

Après un timeout ou une erreur 5xx sur une création, ne recréez pas aveuglément : relisez par référence. Pour une Payment Session, GET /v1/payment-sessions/by-reference?reference=… vous dit si elle existe.

Erreurs du SDK Node.js

Le SDK @kadryza/sdk lève des classes d’erreur selon le statut HTTP. Toutes héritent de KadryzaError et exposent message, code et statusCode.

ClasseStatut HTTPcode exposé par le SDK
KadryzaAuthError401UNAUTHORIZED
KadryzaValidationError400, 422VALIDATION_ERROR
KadryzaNotFoundError404NOT_FOUND
KadryzaDuplicateError409DUPLICATE_REFERENCE
KadryzaGatewayUnavailableError503GATEWAY_UNAVAILABLE
KadryzaNetworkError— (timeout, DNS, réseau)NETWORK_ERROR
KadryzaErrortout autre statut (403, 429, 5xx…)le code de l’API

Pour les statuts 400, 401, 404, 409 et 503, le SDK remplace le code détaillé de l’API par le code générique de la classe : par exemple PROVIDER_RAIL_NOT_READY devient GATEWAY_UNAVAILABLE, et NOT_CANCELLABLE est levé comme KadryzaDuplicateError. Le message d’origine est conservé. Si vous devez distinguer ces cas, appelez l’API HTTP directement.

gestion-erreurs.ts
import Kadryza, { KadryzaError, KadryzaAuthError, KadryzaValidationError, KadryzaDuplicateError, KadryzaGatewayUnavailableError, KadryzaNetworkError } from '@kadryza/sdk' const kadryza = new Kadryza({ apiKey: process.env.KADRYZA_API_KEY! }) try { const session = await kadryza.paymentSessions.create({ reference: 'order_2026_001', amount: 5000, currency: 'XAF', operator: 'AIRTEL', customer_phone: '+23566000000' }) } catch (error) { if (error instanceof KadryzaDuplicateError) { // La référence existe déjà : relire plutôt que recréer. const existing = await kadryza.paymentSessions.retrieveByReference('order_2026_001') } else if (error instanceof KadryzaGatewayUnavailableError) { // Opérateur momentanément indisponible : proposer l'autre opérateur. } else if (error instanceof KadryzaValidationError || error instanceof KadryzaAuthError) { // Erreur d'intégration : corriger, ne pas réessayer en boucle. } else if (error instanceof KadryzaNetworkError) { // Réseau : relire par référence avant toute nouvelle tentative. } else if (error instanceof KadryzaError) { console.error(error.statusCode, error.code, error.message) } else { throw error } }