# Codes d'erreur

> Chaque statut HTTP renvoyé par l'API publique et Discovery, puis les messages d'erreur fréquents par domaine, avec leur cause et leur résolution.

Cette page recense les erreurs que renvoient l'API publique `https://api.wakastart.app/api` et Discovery `https://discovery.wakastart.app`. Les messages sont cités tels que l'API les renvoie : copiez-les dans la recherche de la page pour retrouver leur cause.

## Format d'une erreur

L'API publique renvoie toujours ce corps :

```json
{
  "statusCode": 409,
  "message": "Une invitation est déjà en cours pour cet email",
  "error": "Conflict",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "path": "/api/invitations"
}
```

- `message` est une chaîne, ou un **tableau** de chaînes pour une erreur de validation.
- `error` est un libellé indicatif ; il peut valoir `Internal Server Error` sur une erreur 4xx. Fondez votre traitement sur `statusCode` et `message`.
- Discovery renvoie un corps plus court, sans `timestamp` ni `path` : `{ "statusCode": 404, "message": "not_found", "error": "Not Found" }`.
- Les endpoints du module HDS renvoient le corps d'erreur du module tel quel.

Le détail du format est dans [Conventions](/v1.0/reference-api/conventions#erreurs). Quand vous contactez le support, joignez `timestamp`, `path` et le `message` exact.

## Statuts HTTP

### 200 OK avec un résultat négatif

Quelques endpoints signalent un échec métier dans une réponse `200`, sans statut d'erreur :

| Endpoint | Réponse | Signification |
|---|---|---|
| `GET /api/invitations/verify/{token}` | `{ "valid": false, "errorMessage": "…" }` | Lien inutilisable : voir [Invitations](#invitations) |
| `POST /api/auth/enrich` | `{}` | Le jeton Keycloak envoyé est expiré ou refusé |
| `POST /api/import/users` | `errors` non vide | Certaines lignes du CSV ont été ignorées |
| `POST /api/token/authorize` | `{ "allowed": false, "tokenValid": false }` | Le jeton de l'utilisateur est invalide |
| Discovery `GET /discover/email` | `{ "users": [] }` | Aucun compte pour cet e-mail et ce front, ou `domain` qui ne correspond à aucun hôte IAM de l'application |
| `POST /api/app-keys/introspect` | `{ "active": false }` | La clé présentée à votre wakapp n'est pas acceptée : voir [Clés API des wakapps](#clés-api-des-wakapps) |

### 400 Bad Request

**Cause** : requête mal formée. Champ obligatoire absent, champ inconnu, type ou format incorrect (UUID, WID, e-mail, URL), fichier absent ou d'un type refusé, paramètre d'environnement fourni alors qu'il est déduit de l'appelant, ou règle métier non respectée.

**Résolution** : lisez `message` ; pour une erreur de validation, il liste chaque champ en défaut. Voir [Erreurs de validation](#erreurs-de-validation).

### 401 Unauthorized

**Cause** : aucune identité valide. Jeton absent ou expiré, clé API inconnue, inactive ou expirée, jeton enrichi révoqué.

**Résolution** : renouvelez le jeton auprès de Keycloak, ou vérifiez la clé. Voir [Erreurs d'authentification et d'accès](#erreurs-dauthentification-et-daccès).

### 402 Payment Required

**Cause** : solde de [crédits](/v1.0/reference-api/credits) insuffisant pour une opération payante (import d'utilisateurs, traduction par IA, scan antivirus).

**Résolution** : achetez un pack de crédits, puis relancez l'opération.

### 403 Forbidden

**Cause** : l'appelant est identifié mais n'a pas le droit d'agir. Niveau d'administration trop faible, droit applicatif ou rôle HDS absent, jeton émis pour une autre application, ressource hors de son périmètre, clé API sans portée, ressource système protégée, quota atteint.

**Résolution** : lisez `message`, qui nomme le droit ou le niveau manquant. Voir [Erreurs d'authentification et d'accès](#erreurs-dauthentification-et-daccès).

### 404 Not Found

**Cause** : ressource inconnue, ou invisible pour l'appelant. Discovery répond aussi `404` `not_found` pour un nom d'hôte non déclaré.

**Résolution** : vérifiez l'identifiant (WID ou UUID selon le paramètre) et l'environnement de l'appel.

### 408 Request Timeout

**Cause** : opération du module HDS de plus de 30 secondes (`Request timed out`).

**Résolution** : réessayez ; pour un gros fichier, vérifiez votre débit montant.

### 409 Conflict

**Cause** : doublon (`La valeur du champ "<champs>" existe déjà. Veuillez en choisir une autre.`), suppression bloquée par des objets rattachés, utilisateur ou invitation déjà existants, utilisateur ambigu sur `GET /api/me`, ventes fermées ou compte Stripe pas encore apte à encaisser.

**Résolution** : lisez `message` ; supprimez d'abord les objets rattachés, ou modifiez l'objet existant au lieu d'en créer un.

### 413 Payload Too Large

**Cause** : fichier trop volumineux (`File too large`) : 2 Mo pour un CSV d'import, 100 Mo pour l'antivirus et le module HDS, ou quota de stockage HDS dépassé (`Storage quota exceeded`).

**Résolution** : réduisez ou découpez le fichier. Voir [Limites et quotas](/v1.0/limites).

### 429 Too Many Requests

**Cause** : limite de débit atteinte pour votre adresse IP (`ThrottlerException: Too Many Requests`).

**Résolution** : attendez le nombre de secondes indiqué par l'en-tête `Retry-After-short`, `Retry-After-medium` ou `Retry-After-long`, puis réessayez avec un délai croissant. Voir [Limites de débit](/v1.0/reference-api/conventions#limites-de-débit).

### 500 Internal Server Error

**Cause** : erreur inattendue (`Internal server error`, sans détail), ou échec d'un service tiers relayé : création de compte Keycloak, envoi d'e-mail, service de crédits, moteur de traduction.

**Résolution** : réessayez une fois. Si l'erreur persiste, contactez le support avec `timestamp` et `path`.

### 502 Bad Gateway

**Cause** : un service interne de Wakastart ou un fournisseur (Stripe) a répondu de façon inattendue ; le message commence alors par `Erreur inattendue lors de l'appel à`.

**Résolution** : réessayez après quelques secondes.

### 503 Service Unavailable

**Cause** : service momentanément indisponible ou délai dépassé (`<chemin> service unavailable`, `HDS service unavailable`, `Antivirus service unavailable`), ou vérification de révocation indisponible pour une application HDS (`Auth check unavailable`).

**Résolution** : réessayez avec un délai croissant. Ces erreurs ne modifient aucune donnée.

## Erreurs d'authentification et d'accès

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `401` | `Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)` | Aucune identité valide : en-tête absent, jeton expiré, clé refusée | Renouvelez le jeton ou vérifiez la clé |
| `401` | `Cle API manquante (header x-api-key)` | L'endpoint n'accepte qu'une clé API | Envoyez une clé dans `x-api-key` |
| `401` | `Cle API utilisateur invalide ou expiree` | L'endpoint n'accepte qu'une clé API et celle-ci est refusée | Vérifiez l'état et l'expiration de la clé |
| `401` | `Token revoked` | Jeton enrichi révoqué, par exemple après la désactivation de l'utilisateur | Reconnectez l'utilisateur |
| `401` | `Token enrichi valide requis — authentifiez-vous avec un Bearer token ou une clé API valide` | Lecture du journal d'audit sans identité valide | Authentifiez l'appel |
| `401` | `Keycloak ID manquant dans le contexte utilisateur` | `GET /api/me` sans identité d'utilisateur | Appelez avec le jeton de l'utilisateur |
| `401` | `Environment cannot be deduced: token has no wenv claim` | Le jeton ne porte pas d'environnement | Reconnectez l'utilisateur par le parcours de connexion de l'application |
| `401` | `Environment cannot be deduced: session has no environment` | `GET /api/me` avec une session sans environnement | Reconnectez l'utilisateur par le parcours de connexion de l'application |
| `403` | `Environment cannot be deduced: API key has no environment` | Clé API sans environnement | Demandez une clé rattachée à un environnement |
| `400` | `Environment is deduced from the caller and cannot be provided` | La requête porte un paramètre `env`, `envType` ou `envs`. L'environnement est celui du jeton ou de la clé | Retirez le paramètre ; pour un autre environnement, appelez avec un jeton ou une clé de cet environnement |
| `400` | `Environment cannot be deduced: import requires the caller environment` | Import d'utilisateurs appelé sans environnement déductible | Lancez l'import avec un jeton ou une clé rattachés à l'environnement visé |
| `403` | `Niveau d'administration insuffisant. Requis: <niveau>, Actuel: <niveau>` | Niveau trop faible pour l'endpoint | Utilisez un compte ou une clé de niveau suffisant |
| `403` | `Droit applicatif requis : <code>` | Le profil ne porte pas le droit, ou l'appel utilise le seul jeton enrichi | Ajoutez le droit au profil, ou envoyez le jeton Keycloak |
| `403` | `Rôle(s) HDS requis: <rôles> (mode: any)` | Aucun rôle HDS, ou appel avec le seul jeton enrichi | Attribuez un rôle HDS ; envoyez le jeton Keycloak |
| `403` | `Access denied: token authorized party (azp) is missing` | Le jeton ne désigne aucune application | Utilisez le jeton délivré à votre application |
| `403` | `Access denied: application context is missing` | Le jeton ne porte pas l'application | Vérifiez l'accès de l'utilisateur à l'application dans cet environnement |
| `403` | `Access denied: token authorized party does not match the target application` | Jeton ou clé d'une autre application | Utilisez le jeton de l'application appelée |
| `403` | `Access denied: application configuration unavailable` | Vérification momentanément impossible | Réessayez |
| `403` | `API key without tenant scope cannot list tenant data` | Clé API sans client, réseau ni application | Demandez une clé liée à votre client |
| `503` | `Auth check unavailable` | Application HDS : vérification de révocation indisponible | Réessayez après quelques secondes |

## Erreurs de validation

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `400` | `property <nom> should not exist` | Champ non documenté dans le corps ou la requête | Retirez le champ |
| `400` | `<champ> must be an email`, `<champ> must be a UUID`, `<champ> must not be greater than <n>`… | Valeur hors contrainte | Corrigez la valeur |
| `400` | `Validation failed (<param> must be a valid WID - 6 alphanumeric characters)` | WID mal formé dans le chemin | Envoyez 6 caractères alphanumériques |
| `400` | `Validation failed (<param> must be a valid WID (6 alphanumeric chars) or UUID)` | Identifiant mal formé | Envoyez un WID ou un UUID |
| `400` | `Validation failed (uuid is expected)` | Le chemin attend un UUID | Envoyez l'UUID de l'objet |

## Utilisateurs et organisations

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `403` | `Cannot assign adminLevel <niveau>: exceeds caller privilege ceiling (<niveau>)` | Niveau demandé supérieur à celui de l'appelant | Demandez un niveau au plus égal au vôtre |
| `403` | `Cannot assign hdsRole <rôle>: caller does not possess this role` | Rôle HDS que l'appelant ne possède pas | Faites l'attribution avec un compte qui a ce rôle |
| `403` | `User not found or not accessible` | Utilisateur inconnu ou hors de votre périmètre | Vérifiez le WID |
| `403` | `Accès refusé à ce customer`, `Accès refusé à ce réseau`, `Accès refusé à cette application` | Objet hors de votre périmètre | Vérifiez l'identifiant |
| `403` | `Niveau d'administration insuffisant pour créer un customer` | Création de client réservée aux administrateurs réseau | Faites créer le client par un administrateur réseau |
| `404` | `User with WID <wid> not found`, `Customer with WID <wid> not found`, `Network with WID <wid> not found`, `App with WID <wid> not found` | Objet inconnu | Vérifiez l'identifiant |
| `404` | `Utilisateur non trouvé` | `GET /api/me` : compte sans fiche Wakastart pour l'application | Vérifiez que l'utilisateur a accès à l'application |
| `409` | `Impossible de résoudre l'utilisateur de façon unique (customerId manquant ou invalide)` | `GET /api/me` : le compte appartient à plusieurs clients | Reconnectez l'utilisateur en choisissant son organisation |
| `409` | `La valeur du champ "<champs>" existe déjà. Veuillez en choisir une autre.` | Doublon (e-mail dans un client, sous-domaine, nom) | Choisissez une autre valeur ou modifiez l'objet existant |
| `409` | `Un utilisateur <email> existe déjà pour ce client dans l'environnement <env>` | Création d'un utilisateur dont l'adresse a déjà une fiche chez ce client, dans cet environnement | Modifiez la fiche existante ; une fiche dans un autre environnement n'empêche pas la création |
| `409` | `Impossible de supprimer cet utilisateur car il possède encore des profils…` | Suppression bloquée | Retirez d'abord profils et équipes |
| `409` | `Impossible de supprimer ce client car il possède encore des utilisateurs…` | Suppression bloquée | Retirez d'abord utilisateurs, équipes et fournisseurs d'identité |
| `409` | `Impossible de supprimer le Network "<wid>" : <n> customer(s), <n> host route(s) et <n> network config(s) y sont encore rattachés. Supprimez-les explicitement avant de supprimer ce Network.` | Réseau non vide | Supprimez d'abord ses clients et ses hôtes |
| `503` | `Impossible de joindre l'instance Keycloak [<env>] pour vérifier <email> : <détail>. Réessayez.` | Keycloak de l'environnement injoignable | Réessayez |

## Équipes, profils et droits

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `403` | `Vous n'avez pas les droits pour modifier cette équipe` (ou `supprimer`, `ajouter des membres à`, `retirer des membres de`, `modifier les niveaux dans`) | Niveau trop faible dans l'équipe | Faites l'opération avec un administrateur ou un manager de l'équipe |
| `409` | `Impossible de supprimer cette équipe car elle possède encore des membres. Retirez d'abord les membres de l'équipe.` | Équipe non vide | Retirez les membres |
| `403` | `Les profils système ne peuvent pas être modifiés` (ou `supprimés`) | Profil système | Créez un profil personnalisé |
| `403` | `Les droits système ne peuvent pas être modifiés` (ou `supprimés`) | Droit système | — |
| `409` | `Maximum 200 rights allowed per app` | Plafond de droits atteint | Supprimez des droits inutilisés |
| `409` | `Right with code '<code>' already exists for this app` | Code déjà pris | Choisissez un autre code |
| `409` | `Maximum 50 features allowed per app` | Plafond de fonctionnalités atteint | Supprimez des fonctionnalités |
| `409` | `Impossible de supprimer ce profil car il est encore attribué à des utilisateurs…` | Profil encore utilisé | Retirez d'abord les attributions |

## Invitations

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `400` | `Invalid invitation token format` | Jeton différent de 64 caractères hexadécimaux minuscules | Utilisez le lien reçu sans le modifier |
| `200` / `400` | `Invitation non trouvée`, `Cette invitation a déjà été acceptée`, `Cette invitation a expiré`, `Cette invitation a été annulée` | Lien inutilisable | Demandez une nouvelle invitation ou une relance |
| `400` | `Fournir exactement un des champs customerId ou customerWid` | Champs exclusifs mal renseignés | Envoyez un seul des deux |
| `400` | `Email invalide`, `Les emails jetables ne sont pas autorisés` | Adresse refusée | Utilisez une adresse réelle |
| `400` | `Le realm du network n'est pas provisionné sur l'instance '<env>'. …` | Environnement pas encore prêt pour ce réseau | Contactez le support |
| `403` | `Vous devez avoir au minimum le niveau CUSTOMER_ADMIN pour inviter des utilisateurs` | Niveau insuffisant | — |
| `400` | `Environment is deduced from the caller and cannot be provided` | Champ `envType` envoyé : l'invitation est toujours créée dans l'environnement de l'inviteur | Retirez le champ ; pour inviter dans un autre environnement, appelez avec un jeton ou une clé de cet environnement |
| `403` | `La fonctionnalité invitation n'est pas activée pour ce customer` | Invitations désactivées | Activez les invitations de l'application |
| `403` | `Limite d'invitations atteinte (<n> par mois). Réessayez plus tard.` | Quota de l'inviteur atteint | Attendez, ou demandez le relèvement de la limite |
| `403` | `Customer <id> is outside the caller's tenant scope` | Client hors de votre périmètre | Invitez dans votre propre client |
| `409` | `Un utilisateur avec cet email existe déjà` | Compte déjà présent dans ce client, dans l'environnement de l'inviteur | Attribuez-lui un profil au lieu de l'inviter |
| `409` | `Une invitation est déjà en cours pour cet email` | Invitation en attente dans ce client, dans l'environnement de l'inviteur | Relancez l'invitation existante |
| `500` | `La création de l'invitation a échoué à l'envoi de l'email` | E-mail non parti | Vérifiez le compte d'envoi de l'application, puis réessayez |

## Import d'utilisateurs

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `400` | `Seuls les fichiers CSV sont acceptes` | Fichier d'un autre type | Envoyez un fichier `.csv` |
| `400` | `Fichier CSV requis` | Aucun fichier dans le champ `file` | Joignez le fichier dans `file` |
| `400` | `Le fichier CSV est vide` | Aucune ligne | — |
| `400` | `Le fichier CSV contient <n> lignes, maximum autorise: 500` | Fichier trop long | Découpez-le |
| `400` | `Erreur de parsing CSV: <détail>` | CSV mal formé | Vérifiez séparateurs et guillemets |
| `400` | `Missing customer context` | Appel sans client | Appelez avec un compte ou une clé rattachés à un client |
| `402` | `Insufficient credits` | Solde insuffisant | Achetez un pack de crédits |
| `403` | `Vous ne pouvez importer que dans votre propre customer` | Client cible différent du vôtre | Importez dans votre client |
| `413` | `File too large` | Fichier de plus de 2 Mo | Découpez-le |

## Contenus et traductions

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `403` | `Access denied: you can only access the runtime config of your own application` | Configuration d'une autre application | Utilisez le WID de votre application |
| `403` | `Access denied to this application` | Traductions d'une application hors de votre périmètre | — |
| `404` | `Theme with ID <id> not found` | Thème inconnu | Vérifiez l'identifiant |
| `409` | `This theme is already added to the app` | Thème déjà associé | — |
| `400` | `Cannot remove the default theme. Set another theme as default first.` | Retrait du thème par défaut | Définissez d'abord un autre thème par défaut |
| `409` | `Language with code "<code>" already exists` | Langue déjà au référentiel | Utilisez `POST /api/languages/find-or-create` |
| `400` | `La langue <nom> (<code>) est obligatoire et ne peut pas être supprimée` | Français et anglais obligatoires | — |
| `409` | `Translation key "<clé>" already exists for fileType <type>` | Clé déjà créée | Modifiez sa valeur |
| `404` | `Translation file not found for app '<appWid>', lang '<code>', type '<type>'` | Aucun fichier publié | Publiez les traductions depuis la console |
| `402` | `Insufficient credits` | Traduction par IA sans crédits | Achetez un pack de crédits |
| `500` | `AI translation service unavailable` | Moteur de traduction indisponible | Réessayez |

## Clés API des wakapps

Les opérations `/api/app-keys` (voir [Référence API : clés de votre wakapp](/v1.0/reference-api/cles-api#clés-api-de-votre-wakapp)) renvoient un **code stable dans `message`**, parfois accompagné d'un objet `details`. Fondez votre traitement sur ce code.

| Statut | Code | Cause | Résolution |
|---|---|---|---|
| `400` | `UNKNOWN_RIGHT` | Droit absent du catalogue de l'application pour cet environnement (`details.unknown`) | Corrigez le code du droit |
| `400` | `CONFLICTING_RIGHTS` | Le même droit est à la fois ajouté et retiré (`details.rights`) | Envoyez-le dans une seule des deux listes |
| `400` | `IMMUTABLE_FIELD` | Tentative de modifier le type, l'organisme, l'application ou l'environnement (`details.fields`) | Créez une nouvelle clé |
| `400` | `CUSTOMER_REQUIRED` | Clé technique sans `customerWid` | Indiquez l'organisme |
| `400` | `APP_NOT_ENABLED_FOR_CUSTOMER` | L'application n'est pas activée pour l'organisme | Activez l'application pour ce client |
| `400` | `PLATFORM_APP_FORBIDDEN` | Clé demandée sur l'application Wakastart elle-même | — |
| `400` | `APP_TYPE_NOT_ALLOWED` | L'application n'est pas de type Application (module, service) | — |
| `401` | `CALLER_NOT_RESOLVED` | Le compte de l'appelant est introuvable ou inactif | Reconnectez l'utilisateur |
| `401` | `USER_TOKEN_INVALID` | `user-context` : jeton de l'utilisateur refusé (signature, expiration) ou identité ambiguë | Envoyez un jeton d'accès valide |
| `403` | `RIGHTS_EXCEED_CEILING` | Un droit demandé dépasse les droits de la personne qui agit (`details.missing`) | Retirez ces droits ou faites agir une personne qui les détient |
| `403` | `KEY_TYPE_NOT_ALLOWED` | L'appelant ne peut pas créer ce type de clé, ou fait tourner la clé liée d'un autre utilisateur | Une clé technique est réservée aux administrateurs de l'organisme |
| `403` | `NOT_ORG_ADMIN` | L'appelant est administrateur, mais pas de cet organisme | — |
| `403` | `API_KEY_CANNOT_MANAGE_KEYS` | Opération de gestion appelée avec une clé `sk_` | Appelez avec le jeton de l'utilisateur |
| `403` | `APP_SCOPE_MISMATCH` | `appWid` ou `envType` envoyé et différent de l'application ou de l'environnement du jeton | N'envoyez ni l'un ni l'autre |
| `403` | `APP_NOT_RESOLVED` | Le jeton ne désigne aucune application cliente (client inconnu, module, service, application de la plateforme) | Utilisez le jeton émis pour votre wakapp |
| `403` | `CALLER_APP_KEY_REQUIRED` | `introspect` ou `user-context` appelée sans clé `sk_` valide | Envoyez la clé `sk_` de votre wakapp dans `x-api-key` |
| `403` | `AZP_MISMATCH` | `user-context` : jeton de l'utilisateur émis pour une autre application | Envoyez le jeton émis pour votre wakapp |
| `403` | `USER_TOKEN_ENV_MISMATCH` | `user-context` : jeton d'un autre environnement que votre clé `sk_` | Utilisez la clé `sk_` du même environnement |
| `403` | `USER_NOT_MEMBER` | `user-context` : utilisateur ou organisme inactif, ou sans accès à l'application | — |
| `403` | `Access denied: token authorized party does not match the target application` (pas de code stable) | Le jeton de l'utilisateur a été émis pour une autre application que celle de son réseau. Ce contrôle passe avant tous les autres | Utilisez le jeton émis pour votre wakapp |
| `404` | `NOT_FOUND` | Clé, application ou organisme inexistant, hors de la portée de l'appelant, ou d'une autre application ou d'un autre environnement que ceux du jeton | Vérifiez le WID |
| `409` | `KEY_REVOKED` | Modification ou rotation d'une clé révoquée | Créez une nouvelle clé |
| `429` | — | Limite de débit de `introspect` ou `user-context` atteinte | Attendez la durée de l'en-tête `Retry-After` |
| `503` | `APP_KEYS_DISABLED` | Fonctionnalité momentanément indisponible | Réessayez plus tard |
| `503` | `APP_KEYS_UNAVAILABLE` | Wakastart ne peut pas traiter la demande pour le moment | Réessayez avec un délai croissant |
| `503` | `CONTEXT_SIGNING_UNAVAILABLE` | `user-context` : Wakastart ne peut pas signer de contexte pour le moment ; à l'introspection, `context_token` est alors absent | Réessayez |

Une erreur de validation du corps (champ manquant, champ inconnu, format de droit invalide) renvoie le `400` habituel, avec la liste des messages de validation.

### Réponses du kit à vos clients

Le kit `@wakastellar/wakastart-keys` répond ainsi aux clients qui appellent votre wakapp (voir [Vérifier une clé de votre wakapp](/v1.0/cles-api/verifier-une-cle-de-votre-wakapp)) :

| Statut | Code | Cause |
|---|---|---|
| `401` | `APP_KEY_MISSING` | Pas d'en-tête `Authorization: Bearer` ; la réponse porte `WWW-Authenticate: Bearer` |
| `401` | `APP_KEY_INVALID` | Clé inconnue, révoquée, expirée, d'une autre application ou d'un autre environnement |
| `403` | `APP_KEY_RIGHTS_MISSING` | Droit manquant, listé dans `details.missing` |
| `503` | `WAKASTART_UNAVAILABLE` | Wakastart injoignable, délai dépassé ou réponse inattendue : la clé est refusée faute de vérification |

## Jeton de contexte

Un appel de l'API publique qui porte un [jeton de contexte](/v1.0/cles-api/jeton-de-contexte) dans `X-WakaStart-Context` peut être refusé avec ces codes. En mode `observe`, ces refus sont seulement journalisés par Wakastart, sauf les deux dernières lignes, appliquées quel que soit le mode. En mode `preferred`, tous s'appliquent, sauf l'absence de contexte.

| Statut | Code | Cause |
|---|---|---|
| `403` | `CONTEXT_REQUIRED` | Action en mode `required` ou `bound` appelée sans contexte |
| `401` | `CONTEXT_INVALID` | Contexte expiré (plus de 60 secondes), signature ou émetteur invalide, ou émis pour une autre application ou un autre environnement |
| `403` | `CONTEXT_CUSTOMER_MISMATCH` | L'organisme cible n'est pas celui du contexte |
| `403` | `CONTEXT_OBJECT_OUT_OF_SCOPE` | Un objet de la demande (profil, équipe, invitation, utilisateur) n'appartient pas à l'organisme du contexte, ou un niveau d'administration au-dessus d'Administrateur client est demandé |
| `403` | `CONTEXT_KEY_INACTIVE` | Clé client révoquée, suspendue ou expirée depuis l'émission du contexte |
| `403` | `CONTEXT_AUTH_VERSION_STALE` | Droits ou statut de la clé client modifiés depuis l'émission du contexte |
| `403` | `CONTEXT_USER_INACTIVE` | Contexte « utilisateur » : utilisateur désactivé ou sans accès à l'application |
| `403` | `CONTEXT_REPLAYED` | Mode `bound` : contexte déjà utilisé pour une action |
| `503` | `CONTEXT_UNVERIFIABLE` | Wakastart ne peut pas vérifier le contexte, ou le mode de l'action, pour le moment : l'action est refusée, quel que soit le mode |
| `403` | `Access denied: token authorized party does not match the target application` (pas de code stable) | Requête portant le jeton d'un utilisateur émis pour une autre application que celle de son réseau, refusée avant tout contrôle de contexte, quel que soit le mode |

Un même refus a le même statut et le même code, qu'il soit décidé à l'entrée de l'API ou au moment d'exécuter l'action.

## Antivirus

Les erreurs du module antivirus sont renvoyées avec leur statut et le message générique `Antivirus service error`.

| Statut | Message | Cause probable | Résolution |
|---|---|---|---|
| `400` | `Fichier requis` | Aucun fichier dans `file` | Joignez le fichier |
| `400` | `Antivirus service error` | Fichier refusé par la politique de scan (taille, type, extension), secret de rappel de plus de 64 caractères, appel sans client ni application | Vérifiez le fichier et les paramètres |
| `402` | `Antivirus service error` | Crédits insuffisants | Achetez un pack de crédits |
| `404` | `Antivirus service error` | Scan inconnu | Vérifiez l'identifiant |
| `413` | `File too large` | Fichier de plus de 100 Mo | — |
| `503` | `Antivirus service unavailable` | Module indisponible | Réessayez |

## HDS

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `403` | `HDS path not allowed` | Chemin non autorisé | Utilisez un chemin documenté |
| `403` | `Insufficient HDS permissions for this operation` | Rôle HDS insuffisant pour l'opération | Voir les rôles dans [HDS](/v1.0/reference-api/hds#rôles-hds) |
| `403` | `Cannot delete document under legal hold`, `Cannot delete sealed document` | Document protégé | — |
| `400` | `Vault quota exceeded: <n>/<max>`, `Document quota exceeded: <n>/<max>` | Quota du client atteint | Contactez le support |
| `400` | `Infected file detected — upload denied` | Fichier infecté | — |
| `404` | `Vault not found: <id>`, `Document not found: <id>` | Objet inconnu ou non partagé avec vous | Vérifiez l'identifiant et les partages |
| `408` | `Request timed out` | Opération de plus de 30 secondes | Réessayez |
| `413` | `Storage quota exceeded` | Stockage du client plein | Contactez le support |

## Paiements et crédits

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `403` | `Ce endpoint est réservé aux requêtes émises depuis une WakaApp` | Appel sans le jeton d'un utilisateur de l'application | Appelez avec le jeton de l'utilisateur |
| `400` | `successUrl origin not allowed` (ou `cancelUrl`, `returnUrl`) | URL de retour hors des hôtes autorisés | Utilisez une URL de votre application |
| `400` | `Une session de paiement exige au moins une ligne de commande` | `lineItems` vide | — |
| `404` | `Aucune configuration de facturation pour l'application <appWid>` | Ventes non configurées | Configurez la facturation dans la console |
| `409` | `Les ventes ne sont pas activées pour l'application <appWid>` | Ventes fermées | Ouvrez les ventes dans la console |
| `409` | `Le compte Stripe Connect du Customer <wid> n'est pas encore apte à encaisser` | Inscription Stripe incomplète | Terminez l'inscription Stripe |
| `404` | `Session <id> introuvable pour l'application <appWid>` | Session d'un autre utilisateur | — |
| `404` | `Aucun historique de facturation pour ce client` | L'utilisateur n'a jamais payé | — |
| `404` | `Abonnement <id> inconnu pour <appWid>` | Abonnement d'un autre utilisateur | — |
| `400` | `Pack inconnu : <code>. Valeurs attendues : STARTER, PRO, BUSINESS, ENTERPRISE` | Code de pack invalide | Utilisez un code de `GET /api/pay/packs` |
| `403` | `Missing customer/network context for credit pack purchase` | Appelant sans client ni réseau | — |
| `402` | `Insufficient credits` | Solde insuffisant pour l'opération | Achetez un pack |

## Documents légaux

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `401` | `Cle API manquante (header x-api-key)` | Appel avec un jeton au lieu d'une clé | Utilisez une clé API |
| `404` | `Aucun document légal actif de type <type> pour cette application` | Aucune version en vigueur | Publiez le document dans la console |
| `404` | `LegalDocument "<id>" not found` | Version inconnue | Relisez la liste des documents |

## Discovery

| Statut | Message | Cause | Résolution |
|---|---|---|---|
| `400` | `email must be an email` | Adresse absente ou mal formée | — |
| `400` | `subdomain must contain only alphanumeric characters and hyphens` | Sous-domaine invalide | — |
| `400` | `property <nom> should not exist` | Paramètre non documenté | Retirez-le |
| `400` | `invalid_request` | `POST /discover/start-login` sans `host` | Envoyez toujours le nom d'hôte complet de la page |
| `404` | `not_found` | Aucun realm ne correspond au nom d'hôte | Envoyez le nom d'hôte complet ; faites déclarer l'hôte pour l'environnement |
| `429` | `ThrottlerException: Too Many Requests` | Limite de débit atteinte | Attendez avant de réessayer |
