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

# Codes d'erreur & réponses

> L'enveloppe de réponse, les codes d'erreur stables et comment ils se mappent aux codes de statut HTTP.

## Enveloppe de réponse

Chaque réponse de style action suit une forme cohérente. En cas de succès :

```json theme={null}
{ "success": true, "data": { /* … */ } }
```

En cas d'échec :

```json theme={null}
{
  "success": false,
  "error": "Variant is required",        // lisible par l'homme, pour vos logs
  "errorCode": "VARIANT_REQUIRED",        // stable, se brancher sur ceci
  "fieldErrors": [                          // présent pour la validation d'entrée
    { "field": "variantId", "code": "VARIANT_REQUIRED" }
  ]
}
```

Les réponses peuvent aussi porter `businessRuleWarnings` (quand une règle a alerté mais autorisé l'action)
et `approvalRequested` (quand une politique d'approbation a intercepté une validation).

**Toujours se brancher sur `errorCode`, pas sur le texte `error`** — le texte est pour les logs
et peut changer ou être localisé ; le code est stable.

## Mappage du statut HTTP

Les erreurs sont catégorisées et la catégorie détermine le statut HTTP (avec quelques
remplacements par code) :

| Catégorie                                 | HTTP  | Exemples                                                         |
| ----------------------------------------- | ----- | ---------------------------------------------------------------- |
| Validation                                | `400` | `VALIDATION_ERROR`, `MISSING_REQUIRED_FIELD`, `VARIANT_REQUIRED` |
| Auth                                      | `401` | `UNAUTHORIZED`, `FORBIDDEN`                                      |
| Non trouvé                                | `404` | `RECORD_NOT_FOUND`, `PLAN_NOT_FOUND`                             |
| Métier                                    | `422` | `BUSINESS_RULE_VIOLATION`, `INSUFFICIENT_STOCK`                  |
| Limite de débit                           | `429` | `RATE_LIMIT_EXCEEDED`                                            |
| Externe                                   | `502` | `EXTERNAL_SERVICE_ERROR`, `EXTERNAL_SERVICE_TIMEOUT`             |
| Base de données / Configuration / Inconnu | `500` | `DATABASE_ERROR`, `UNKNOWN_ERROR`                                |

Un remplacement notable : `PLAN_ALREADY_VALIDATED` retourne **409 Conflict** plutôt que 422.

## Codes d'erreur courants

| Code                                  | Signification                                         | Que faire                                                       |
| ------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------- |
| `UNAUTHORIZED`                        | Token manquant, invalide, révoqué ou expiré           | Ré-authentifiez-vous / émettez un nouveau token                 |
| `FORBIDDEN`                           | Token manque la permission requise                    | Accordez la permission sur le token ; ne réessayez pas tel quel |
| `VALIDATION_ERROR`                    | L'entrée a échoué la validation                       | Inspectez `fieldErrors` ; corrigez la charge utile              |
| `RECORD_NOT_FOUND` / `PLAN_NOT_FOUND` | La ressource n'existe pas (ou pas dans votre org)     | Vérifiez l'id ; ne réessayez pas                                |
| `BUSINESS_RULE_VIOLATION`             | Une règle métier a bloqué l'action                    | Lisez le message / avertissements ; ajustez la requête          |
| `PLAN_ALREADY_VALIDATED`              | Le plan est au-delà de l'état sur lequel vous agissez | Re-récupérez le statut actuel du plan                           |
| `RATE_LIMIT_EXCEEDED`                 | Trop de requêtes (si appliqué en amont)               | Retournez-vous et réessayez                                     |
| `DATABASE_ERROR` / `UNKNOWN_ERROR`    | Erreur serveur inattendue                             | Réessayez une fois ; escaladez si persistant                    |

Il y a plus d'une centaine de codes spécifiques (validation, opérations plan/article, téléchargement de fichier,
tokens API, …). Chaque endpoint documente ceux qu'il peut retourner dans l'onglet **Référence API**.

## Messages localisés

Les codes d'erreur sont découplés du texte d'affichage pour que les messages puissent être affichés dans la
langue de l'utilisateur. Dans l'application web, les codes sont traduits en anglais ou en français ; les
intégrateurs doivent se fier au **code** et rendre leur propre message si nécessaire.