ERREURS & CODES DE RETOUR

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

Champ	Description	Obligatoire
`error`	Code d’erreur standardisé	Oui
`message`	Message lisible humainement	Oui
`details`	Détails d’erreurs	Non
`details.field`	Champ du payload concerné	Non
`details.reason`	Cause technique ou métier	Non
`details.expected`	Valeur ou format attendu	Non
`timestamp`	ISO-8601 UTC	Oui
`requestId`	Identifiant de traçabilité	Oui

Table des codes d’erreur standardisés

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

error	Quand l’utiliser
`SEC_INVALID_SIGNATURE`	Signature incorrecte
`SEC_REPLAY_DETECTED`	Nonce déjà utilisé
`SEC_TIMESTAMP_EXPIRED`	Timestamp hors fenêtre
`SEC_UNAUTHORIZED_SENDER`	Certificat ou clé invalide
`SEC_SPOOFING_SUSPECTED`	Origine incohérente

B. Erreurs techniques (`TECHNICAL`)

error	Quand l’utiliser
`TECH_MALFORMED_PAYLOAD`	JSON invalide
`TECH_BANK_UNAVAILABLE`	Banque indisponible
`TECH_CONNECTOR_TIMEOUT`	Timeout
`TECH_DUPLICATE_REQUEST`	Requête déjà traitée

C. Erreurs métier (`BUSINESS`)

error	Quand l’utiliser
`BUS_INVALID_IBAN`	IBAN invalide
`BUS_ACCOUNT_BLOCKED`	Compte bloqué
`BUS_INSUFFICIENT_FUNDS`	Solde insuffisant
`BUS_LIMIT_EXCEEDED`	Plafond dépassé
`BUS_FORBIDDEN_CREDITOR`	Créancier interdit
`BUS_ORDER_REJECTED`	Ordre 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

HTTP	Catégorie	Signification
200	-	Traitement réussi
202	-	Traitement accepté
400	BUSINESS	Erreur métier
401	SECURITY	Authentification échouée
403	SECURITY	Accès interdit
409	TECHNICAL	Conflit / Idempotence
500	TECHNICAL	Erreur interne
503	TECHNICAL	Service 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.

Getting started

Comunication

Sécurité

Format JSON

Objectif

Principes fondamentaux

Catégorisation des erreurs

Catégories

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

2. Erreurs techniques (`TECHNICAL`)

3. Erreurs métier (`BUSINESS`)

4.1.1 Structure JSON d’une erreur

Description champ par champ

Table des codes d’erreur standardisés

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

B. Erreurs techniques (`TECHNICAL`)

C. Erreurs métier (`BUSINESS`)

5.6 Correspondance HTTP / Erreurs

5.7 Traçabilité des erreurs

​Objectif

​Principes fondamentaux

​Catégorisation des erreurs

​Catégories

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

​2. Erreurs techniques (`TECHNICAL`)

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

​4.1.1 Structure JSON d’une erreur

​Description champ par champ

​Table des codes d’erreur standardisés

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

​B. Erreurs techniques (TECHNICAL)

​C. Erreurs métier (BUSINESS)

​5.6 Correspondance HTTP / Erreurs

​5.7 Traçabilité des erreurs

Objectif

Principes fondamentaux

Catégorisation des erreurs

Catégories

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

2. Erreurs techniques (`TECHNICAL`)

3. Erreurs métier (`BUSINESS`)

4.1.1 Structure JSON d’une erreur

Description champ par champ

Table des codes d’erreur standardisés

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

B. Erreurs techniques (`TECHNICAL`)

C. Erreurs métier (`BUSINESS`)

5.6 Correspondance HTTP / Erreurs

5.7 Traçabilité des erreurs