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

# Codes d'erreur

> L'enveloppe d'erreur partagée et la correspondance entre les ResultCode du noyau et les statuts HTTP.

Chaque échec de l'API renvoie l'enveloppe d'erreur partagée, dont le champ
`code` est un **`ResultCode`** du noyau. Le statut HTTP de la réponse est dérivé
de ce code par une correspondance unique.

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "…",
    "statusCode": 404
  }
}
```

## Correspondance `ResultCode` → statut HTTP

| `ResultCode`            | Statut HTTP | Signification                                                                      |
| ----------------------- | ----------- | ---------------------------------------------------------------------------------- |
| `Ok`                    | `200`       | Succès.                                                                            |
| `ValidationFailed`      | `400`       | Requête mal formée ; porte `fieldErrors`.                                          |
| `Unauthorized`          | `401`       | Authentification requise ou invalide.                                              |
| `Forbidden`             | `403`       | Authentifié, mais scope/permission insuffisant.                                    |
| `NotFound`              | `404`       | Ressource introuvable.                                                             |
| `Conflict`              | `409`       | Conflit (ex. version attendue obsolète).                                           |
| `BusinessRuleViolation` | `422`       | Requête bien formée mais violant une règle métier (panier vide, solde non réglé…). |
| `Internal`              | `500`       | Erreur interne (repli défensif).                                                   |

Cette table est la **source unique** : le statut d'une réponse d'erreur et le
`statusCode` porté dans l'enveloppe en sont tous deux dérivés — ils ne peuvent
pas diverger.

## Les erreurs dérivées par opération

Pour chaque opération documentée, l'ensemble des erreurs possibles est **dérivé**
de la correspondance ci-dessus :

* `400` et `500` sont toujours possibles ;
* `401` dès que l'opération est authentifiée ;
* `403` dès que l'opération est protégée par un scope ;
* `404` lorsqu'un paramètre de chemin désigne une ressource unique ;
* `409` sur une route sujette à conflit ;
* `422` sur une mutation soumise à une règle métier.

## `fieldErrors`

Sur `VALIDATION_FAILED` (`400`), l'enveloppe porte en plus `fieldErrors` : une
liste d'objets `{ field, message }` indiquant précisément quels champs ont été
rejetés.

```json theme={null}
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "…",
    "statusCode": 400,
    "fieldErrors": [
      { "field": "email", "message": "invalid email" }
    ]
  }
}
```