> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corelink.dhi-cm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ERREURS & CODES DE RETOUR

> Principes de gestion des erreurs et rejets

## 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

```json theme={null}
{
  "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.