Gestion des Erreurs

L'API Collect utilise les codes HTTP standards. Les erreurs métier sont structurées dans un objet error 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
Paiement créé.

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, scope insuffisant).
Name
404 Not Found
Description
Référence ou ressource introuvable.
Name
429 Too Many Requests
Description
Limite de débit dépassée. Respectez Retry-After.

Erreur serveur (5xx)

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

Format de réponse d'erreur

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone",
    "message": "Numéro invalide pour BJ.",
    "doc_url": "https://docs.fluxxpay.me/errors/invalid_phone"
  }
}

Name
error.code
Type
string
Description
Code machine pour votre logique applicative.
Name
error.message
Type
string
Description
Message lisible pour le support ou les logs.
Name
error.param
Type
string
Description
Champ concerné, si applicable.

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 (100 unités majeures en XOF).
Name
invalid_otp
Description
Code OTP Coris invalide.
Name
otp_not_required
Description
Confirmation OTP non attendue pour ce paiement.
Name
missing_idempotency_key
Description
En-tête Idempotency-Key requis mais absent.
Name
insufficient_scope
Description
La clé API n'a pas le scope requis (collect:read, collect:write, collect:refund).
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.me/api/v1/collect/payments', {
  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(() => ({}))
  const code = body.error?.code ?? body.code
  switch (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?.message ?? body.error ?? res.statusText)
}

Avec le SDK : les erreurs lèvent FluxxCollectError (status, code, body).

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 error.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.

Voir aussi

Référence API Collect SDK @fluxx/collect