Gestion des Erreurs

L'API Collect utilise les codes HTTP standards. Les erreurs métier incluent un champ code pour un traitement programmatique.

Codes de statut HTTP

Succès (2xx)

Name
200 OK
Description
Requête réussie (lecture, rejeu idempotent, confirmation OTP).
Name
201 Created
Description
Collecte créée.

Erreur client (4xx)

Name
400 Bad Request
Description
Paramètres invalides (opérateur, téléphone, montant, OTP, etc.).
Name
401 Unauthorized
Description
Clé API manquante ou invalide.
Name
403 Forbidden
Description
Accès refusé (compte, clé, marchand).
Name
404 Not Found
Description
Référence ou ressource introuvable.
Name
429 Too Many Requests
Description
Limite de débit dépassée.

Erreur serveur (5xx)

Name
500 Internal Server Error
Description
Erreur interne (collect_failed, collect_confirm_failed).

Format de réponse d'erreur (API Collect)

{
  "error": "Numéro invalide pour BJ.",
  "code": "invalid_phone"
}

Name
error
Type
string
Description
Message lisible pour le support ou les logs.
Name
code
Type
string
Description
Code machine pour votre logique applicative.

Les erreurs de validation DRF (champ manquant) peuvent renvoyer un objet par champ — traitez le corps JSON selon le statut HTTP.

Codes métier API Collect

Name
invalid_operator
Description
Pays ou opérateur non supporté.
Name
invalid_phone
Description
Numéro incompatible avec le pays.
Name
amount_too_low
Description
Montant sous le minimum XOF (10 000 centimes).
Name
invalid_otp
Description
Code OTP Coris invalide.
Name
otp_not_required
Description
Confirmation OTP non attendue pour cette collecte.
Name
missing_idempotency_key
Description
En-tête Idempotency-Key requis mais absent.
Name
not_found
Description
Référence marchand inconnue.
Name
collect_failed
Description
Erreur interne lors de la collecte.
Name
collect_confirm_failed
Description
Erreur interne lors de la confirmation OTP.

Exemple de gestion (JavaScript)

const res = await fetch('https://api.fluxxpay.com/api/v1/collect/mobile-money/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'collect-ORDER-123',
  },
  body: JSON.stringify(payload),
})

if (!res.ok) {
  const body = await res.json().catch(() => ({}))
  switch (body.code) {
    case 'invalid_operator':
    case 'invalid_phone':
    case 'amount_too_low':
      // Afficher une erreur utilisateur
      break
    case 'collect_failed':
      // Erreur serveur — retry limité ou support
      break
    default:
      if (res.status === 401) {
        // Clé API
      }
  }
  throw new Error(body.error || res.statusText)
}

Bonnes pratiques

Name
Idempotence
Description
Sur retry réseau, réutilisez la même Idempotency-Key et la même reference.
Name
Logs
Description
Enregistrez code, reference et statut HTTP — pas la clé API.
Name
429
Description
Backoff exponentiel ; respectez Retry-After si présent.
Name
Support
Description
Fournissez reference, id transaction et horodatage au support FluxxPay.

Prochaines étapes

Référence API Collect