Skip to main content

​
Objectif

Cette section définit les **règles de gestion des erreurs **applicables à tous les échanges entre la Banque et le Connecteur Bancaire. Elle vise à garantir :
  • une interprétation univoque des erreurs,
  • une gestion cohérente des rejets,
  • une traçabilité complète pour les équipes techniques et support.

​
Principes fondamentaux

  • Toute erreur doit être déterministe
  • Toute erreur doit être tracable
  • Une erreur de sécurité entraîne un **rejet immédiat**
  • Une erreur finale est **non rejouable**, sauf indication contraire

​
Catégorisation des erreurs

Typologie des erreurs supportées

​
Catégories

Les erreurs sont classées en trois catégories :

​
1. Erreurs de sécurité (`SECURITY`)

Erreurs liées à :
  • l’authentification,
  • la signature,
  • l’anti-rejeu,
  • l’intégrité des messages.
Ces erreurs entraînent un **rejet immédiat**.

​
2. Erreurs techniques (`TECHNICAL`)

Erreurs liées à :
  • indisponibilité système,
  • timeout,
  • erreurs réseau,
  • erreurs de format non métier.
Ces erreurs peuvent être **rejouées**.

​
3. Erreurs métier (`BUSINESS`)

Erreurs liées à :
  • règles bancaires,
  • solde insuffisant,
  • compte invalide,
  • devise non supportée.
Ces erreurs sont **définitives**.

​
4.1.1 Structure JSON d’une erreur

{
  "error": "SEC_TIMESTAMP_EXPIRED",
  "message": "The provided timestamp is older than the allowed validity window.",
  "details": {
    "field": "timestamp",
    "reason": "Timestamp outside allowed 5-minute window",
    "expected": "A timestamp not older than 300 seconds"
  },
  "timestamp": "2025-11-19T15:20:45Z",
  "requestId": "REQ-889911"
}

​
Description champ par champ

ChampDescriptionObligatoire
errorCode d’erreur standardiséOui
messageMessage lisible humainementOui
detailsDétails d’erreursNon
details.fieldChamp du payload concernéNon
details.reasonCause technique ou métierNon
details.expectedValeur ou format attenduNon
timestampISO-8601 UTCOui
requestIdIdentifiant de traçabilitéOui

​
Table des codes d’erreur standardisés

​
A. Erreurs de sécurité (SECURITY)

errorQuand l’utiliser
SEC_INVALID_SIGNATURESignature incorrecte
SEC_REPLAY_DETECTEDNonce déjà utilisé
SEC_TIMESTAMP_EXPIREDTimestamp hors fenêtre
SEC_UNAUTHORIZED_SENDERCertificat ou clé invalide
SEC_SPOOFING_SUSPECTEDOrigine incohérente

​
B. Erreurs techniques (TECHNICAL)

errorQuand l’utiliser
TECH_MALFORMED_PAYLOADJSON invalide
TECH_BANK_UNAVAILABLEBanque indisponible
TECH_CONNECTOR_TIMEOUTTimeout
TECH_DUPLICATE_REQUESTRequête déjà traitée

​
C. Erreurs métier (BUSINESS)

errorQuand l’utiliser
BUS_INVALID_IBANIBAN invalide
BUS_ACCOUNT_BLOCKEDCompte bloqué
BUS_INSUFFICIENT_FUNDSSolde insuffisant
BUS_LIMIT_EXCEEDEDPlafond dépassé
BUS_FORBIDDEN_CREDITORCréancier interdit
BUS_ORDER_REJECTEDOrdre rejeté globalement
Règles
  • Les erreurs métier sont **définitives**
  • Aucun retry automatique n’est autorisé
  • Le statut final est `FAILED`

​
5.6 Correspondance HTTP / Erreurs

Correspondance entre codes HTTP et erreurs métier
HTTPCatégorieSignification
200-Traitement réussi
202-Traitement accepté
400BUSINESSErreur métier
401SECURITYAuthentification échouée
403SECURITYAccès interdit
409TECHNICALConflit / Idempotence
500TECHNICALErreur interne
503TECHNICALService indisponible

​
5.7 Traçabilité des erreurs

Suivi et analyse des erreurs. Les informations doivent permettre :
  • l’identification rapide de la cause,
  • la reconstitution du flux,
  • la résolution des incidents.
Les erreurs doivent être conservées conformément aux exigences réglementaires et contractuelles.