Codes d’erreur

Format de réponse d’erreur

{
  "success": false,
  "error": {
    "code": "IDEMPOTENCY_KEY_REQUIRED",
    "message": "Le header X-Idempotency-Key est obligatoire.",
    "http_status": 400,
    "path": "/v1/payments",
    "timestamp": "2026-10-03T10:00:00.000Z"
  }
}

code est stable : basez votre logique dessus, pas sur message.
Les erreurs de validation des champs renvoient 400 avec code: "BAD_REQUEST", le premier message en message et la liste complète en details.
Quand une erreur n’a pas de code métier, code reprend le statut HTTP (BAD_REQUEST, NOT_FOUND, RATE_LIMIT_EXCEEDED…).
Les erreurs 5xx renvoient le code du statut HTTP (SERVICE_UNAVAILABLE, INTERNAL_ERROR…) et un message générique, sans détail technique.

Authentification

Code	HTTP	Description
`MISSING_API_KEY`	401	Header `Authorization` absent
`INVALID_AUTH_FORMAT`	401	Header mal formé (attendu : `Bearer sk_...`)
`INVALID_KEY_TYPE`	401	Clé autre qu’une clé secrète `sk_...`
`INVALID_API_KEY`	401	Clé inconnue ou révoquée
`MERCHANT_INACTIVE`	401	Compte marchand désactivé
`PRODUCTION_KEY_DISABLED`	401	Clé live alors que la production n’est pas ouverte pour ce compte
`PAID_SUBSCRIPTION_REQUIRED`	403	Clé live ou paiement live sans accès production en cours

Création de paiement

Code	HTTP	Description
`IDEMPOTENCY_KEY_REQUIRED`	400	Header `X-Idempotency-Key` absent
`INVALID_IDEMPOTENCY_KEY`	400	Clé d’idempotence de plus de 128 caractères
`BAD_REQUEST`	400	Champ invalide (montant hors 100–5 000 000, téléphone non international, `provider` autre que `ORANGE_MONEY`, métadonnées de test en production, moyen de paiement en maintenance…)
`MERCHANT_PAYMENT_DISABLED`	403	Le compte n’est pas autorisé à créer ce paiement
—	409	Même `X-Idempotency-Key` réutilisée pour une demande différente
`RATE_LIMIT_EXCEEDED`	429	Plus de 10 créations par minute

Programme Partenaires SPAY

Code	HTTP	Description
`PARTNER_PRODUCT_REQUIRED`	400	Paiement ou lien live sans produit du catalogue validé
`PARTNER_ITEMS_INVALID`	400	`items` mal formé
`PARTNER_PRODUCT_NOT_FOUND`	400	Produit inconnu
`PARTNER_PRODUCT_NOT_APPROVED`	400	Produit non validé par SahelPay
`PARTNER_AMOUNT_MISMATCH`	400	`amount` différent du total du catalogue

Liens de paiement

Code	HTTP	Description
`PAYMENT_LINK_NOT_FOUND`	404	Lien introuvable (slug invalide ou inconnu)

Système

Code	HTTP	Description
`RATE_LIMIT_EXCEEDED`	429	Trop de requêtes
`INTERNAL_ERROR`	500	Erreur interne
`SERVICE_UNAVAILABLE`	503	Service momentanément indisponible

Certaines routes renvoient encore 200 avec { "success": false, "message": "..." } quand une ressource est introuvable (GET /v1/payments/{id}/status, /details, /search). Testez toujours success.

Billing — SDK 1.3.0

HTTP	Code courant	Cause / action
400	`BAD_REQUEST` / `VALIDATION_ERROR`	Identité manquante, plan inactif, date d’essai invalide ou import hors période courante
404	`NOT_FOUND`	Plan, abonnement ou facture absent/hors application ou mode
409	`CONFLICT`	Référence externe réutilisée avec d’autres paramètres

Le SDK conserve le code renvoyé par l’API. Les six créations Billing supportent le rejeu persistant avec X-Idempotency-Key. Sans ce header, seules les références naturelles de checkout/import dédupliquent ces créations.

400 INVALID_IDEMPOTENCY_KEY : clé vide ou longueur hors 1–128.
409 IDEMPOTENCY_KEY_REUSED : même clé/portée/route avec un autre corps JSON.
400 BAD_REQUEST : curseur invalide ou incompatible avec la portée/les filtres.
409 INVOICE_PAYMENT_SETTLEMENT_PENDING : paiement réussi en cours d’imputation ; relire l’état et ne pas demander au client de payer encore.

Voir le contrat Billing.

Démarrer

Guides

Ressources

Codes d'erreur

Codes d’erreur

Format de réponse d’erreur

Authentification

Création de paiement

Programme Partenaires SPAY

Liens de paiement

Système

Billing — SDK 1.3.0

​Codes d’erreur

​Format de réponse d’erreur

​Authentification

​Création de paiement

​Programme Partenaires SPAY

​Liens de paiement

​Système

​Billing — SDK 1.3.0

Codes d’erreur

Format de réponse d’erreur

Authentification

Création de paiement

Programme Partenaires SPAY

Liens de paiement

Système

Billing — SDK 1.3.0