Skip to main content

​
Format des erreurs

Toutes les erreurs sont retournées en JSON : 
{
  "timestamp": "2026-03-19T10:00:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Description détaillée de l'erreur",
  "path": "/api/v1/transaction/collect"
}

​
400 — Bad Request

La requête est malformée ou contient des données invalides.
CauseSolution
Champ obligatoire manquant (phoneNumber, amount, externalId)Vérifiez que tous les champs requis sont présents
amount négatif ou nulLe montant doit être strictement positif
externalId non uniqueChaque transaction doit avoir un UUID unique
Format de phoneNumber invalideFormat international sans + (ex : 237690000000)
transferMethod invalideVoir la liste des opérateurs dans Transactions
countryName incohérent avec transferMethodEx : OMCM requiert countryName: "CAMEROON"
{
  "status": 400,
  "error": "Bad Request",
  "message": "Le champ 'phoneNumber' est obligatoire",
  "path": "/api/v1/transaction/collect"
}

​
401 — Unauthorized

L’authentification a échoué.
CauseSolution
Header apiKey absentAjoutez le header apiKey à votre requête
Header apiId absentAjoutez le header apiId à votre requête
Token Bearer manquant ou expiréRenouvelez via POST /public/refresh_token
apiKey invalide ou révoquéeRégénérez votre clé API depuis l’espace partenaire
apiId ne correspond pas à la apiKeyVérifiez que vous utilisez la bonne paire clé/ID
{
  "status": 401,
  "error": "Unauthorized",
  "message": "apiKey manquante ou invalide",
  "path": "/api/v1/transaction/collect"
}

​
403 — Forbidden

Accès refusé, même avec une authentification valide.
CauseSolution
Adresse IP non autoriséeAjoutez votre IP à la liste blanche (espace partenaire)
Compte utilisateur bloquéContactez le support Remita
Application produit désactivéeVérifiez le statut de votre application
Service de transfert désactivé pour ce compteContactez le support pour activer le service
{
  "status": 403,
  "error": "Forbidden",
  "message": "L'adresse IP 203.0.113.42 n'est pas autorisée",
  "path": "/api/v1/transaction/collect"
}

​
404 — Not Found

La ressource demandée n’existe pas.
CauseSolution
Transaction introuvable avec l’id fourniVérifiez l’identifiant de la transaction
Endpoint inexistantVérifiez l’URL (majuscules/minuscules, slashes)
{
  "status": 404,
  "error": "Not Found",
  "message": "Transaction 'txn_xxx' introuvable",
  "path": "/api/v1/transaction/transaction-status"
}

​
500 — Internal Server Error

Erreur interne côté Remita.
CauseSolution
Erreur temporaire opérateur (Orange, MTN)Réessayez après quelques secondes
Erreur système RemitaContactez le support avec le timestamp et le path
{
  "status": 500,
  "error": "Internal Server Error",
  "message": "Erreur de communication avec l'opérateur MTN",
  "path": "/api/v1/transaction/deposit"
}

​
Statuts de transaction échoués

Quand une transaction atteint le statut FAILED :
MessageCause probable
Solde insuffisantLe client n’a pas assez de solde sur son compte mobile money
Numéro invalideLe numéro n’existe pas chez l’opérateur
Transaction annulée par le clientLe client a refusé la confirmation sur son téléphone
Timeout opérateurL’opérateur n’a pas répondu dans le délai imparti
Compte non inscritLe numéro n’est pas enregistré au service mobile money

​
Gestion des erreurs — Exemples

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

switch (response.statusCode()) {
    case 200 -> System.out.println("Succès: " + response.body());
    case 400 -> System.err.println("Requête invalide: " + response.body());
    case 401 -> System.err.println("Non authentifié: vérifiez apiKey/apiId/token");
    case 403 -> System.err.println("Accès refusé: vérifiez votre IP whitelist");
    case 404 -> System.err.println("Ressource introuvable");
    case 500 -> System.err.println("Erreur serveur: réessayez plus tard");
    default  -> System.err.println("Erreur inattendue: " + response.statusCode());
}

​
Checklist de débogage

Les headers apiKey et apiId sont présents et corrects
Le header Authorization: Bearer <token> est présent et non expiré
L’IP de votre serveur est dans la liste blanche
Le corps de la requête est du JSON valide (Content-Type: application/json)
Tous les champs obligatoires sont présents
L’externalId est un UUID valide et unique
Le phoneNumber est au format international (ex : 237690000000)
Le amount est un nombre strictement positif
transferMethod et countryName sont cohérents

​
Support

Si le problème persiste, contactez le support Remita en fournissant :
  • Le timestamp de l’erreur
  • Le path concerné
  • Votre apiId (jamais votre apiKey)
  • Le corps de votre requête (sans données sensibles)