Chargement de vos clés API…

Erreurs

Format des erreurs et codes principaux retournés par l'API.

Format JSON

Toutes les erreurs retournent un corps JSON normalisé :

{
  "error": "ValidationError",
  "message": "Request validation failed",
  "statusCode": 400,
  "fields": [
    { "field": "order.amount", "message": "Required", "code": "invalid_type" }
  ],
  "requestId": "c65236d2-0f90-424a-88a9-515dc5d320fb"
}

Conservez requestId dans vos logs : c'est ce qu'on vous demandera en cas de support.

Codes HTTP

Code	Label	Signification
200	OK	Requête réussie.
201	Created	Ressource créée avec succès.
204	No Content	Suppression réussie, pas de corps.
400	Bad Request	Paramètres invalides ou manquants.
401	Unauthorized	Clé API manquante ou invalide.
403	Forbidden	Permission insuffisante ou IP non autorisée.
404	Not Found	Ressource introuvable.
409	Conflict	Conflit (idempotence, doublon, état incompatible).
422	Unprocessable Entity	Validation métier échouée.
429	Too Many Requests	Rate limit dépassé. Réessayez après le délai indiqué dans `Retry-After`.
500	Internal Server Error	Erreur côté Mobupay. Si persistant, contactez le support.
502	Bad Gateway	Erreur du processeur en aval (banque, réseau carte, etc.).

Codes d'erreur métier

Le champ error du JSON contient un code machine que vous pouvez switcher dans votre code. Codes les plus fréquents :

Code	Signification
VALIDATION_ERROR	Champ requis manquant ou mal formaté. Voir `fields` dans la réponse.
AUTHENTICATION_ERROR	Clé API invalide ou révoquée.
PERMISSION_ERROR	La clé n'a pas la permission requise pour cette opération.
NOT_FOUND	L'identifiant demandé n'existe pas dans votre compte.
IDEMPOTENCY_KEY_CONFLICT	Même clé d'idempotence avec un body différent. Réessayez avec une nouvelle clé.
INVALID_PAYMENT_STATUS	Opération impossible dans l'état actuel du paiement (ex : capturer un paiement déjà capturé).
REFUND_AMOUNT_EXCEEDS_PAYMENT	Le montant à rembourser dépasse le montant initial.
FREE_PAYMENT_UNSUPPORTED	`order.amount` doit être strictement positif : un paiement gratuit ne peut pas être créé. Un net carte nul n'est autorisé qu'en mode plateforme entièrement couvert par une remise (`order.discount = order.amount`).
PLATFORM_CONFIG_REQUIRED_NET0	Capture d'un paiement à net 0 (entièrement financé par la plateforme) sans `order.platformConfig` : le split est requis à la capture pour ventiler aux sous-marchands.
PARTIAL_REFUND_UNSUPPORTED_NET0	Remboursement partiel d'un paiement à net 0 : seul le remboursement total est possible (le net carte est nul). Omettez `amountCents`.
CAPTURE_AMOUNT_MISMATCH	Le montant capturé doit être égal à `order.amount − order.discount` (la carte n'est débitée que du net ; la plateforme abonde le complément).
ENTRY_AMOUNT_MISMATCH	Le montant d'une entrée `platformConfig` ne correspond pas à la somme de ses articles TTC remisés (`Σ(unitPrice×qty − discount) − discount`).
PLATFORM_SELF_NO_COMMISSION	Une entrée `platformConfig` marquée `isPlatform` ne peut porter aucune commission (`platformCommission` / `itemPlatformCommission` / `orderPlatformCommission`) : on ne se prélève pas de commission sur soi-même.
PLATFORM_SELF_REQUIRES_SUBMERCHANT	Une entrée `isPlatform` requiert au moins une autre entrée sous-marchand. Pour une commande de la plateforme pour elle-même seule, utilisez le mode e-commerce (sans `platformConfig`).
CAPTURE_AMOUNT_BELOW_AUTHORIZED	À la capture, `order.amount` (brut) doit égaler le montant autorisé. Une réduction du montant débité n'est permise que via un `order.discount` explicite ; une sous-capture « sèche » est refusée (elle masquerait une intégration incomplète).
RATE_LIMITED	Trop de requêtes. Voir header `Retry-After`.
REFUND_PROCESSOR_FAILED	Erreur côté processeur carte. Réessayez plus tard ou contactez le support.

Bonnes pratiques

Switcher sur statusCode + error (jamais sur le texte de message qui peut évoluer).
Retry uniquement sur 429 (avec backoff) et 502/503/504 (transient).
Logger requestId systématiquement.
Pour les 4xx : corriger côté client avant de retry, sinon vous bouclez à perte.