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

# Erreurs

> La forme d'une erreur, chaque code que répond l'API, et que faire pour chacun.

Chaque erreur de l'API répond en JSON avec au moins trois champs :

```json 422 Unprocessable Content theme={null}
{
    "message": "Non envoyé : ada@example.com figure sur la liste de suppression.",
    "code": "recipients_suppressed",
    "doc_url": "https://docs.lekalao.com/fr/errors#recipients_suppressed",
    "data": { "id": "e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10", "status": "failed", "failure_code": "recipients_suppressed" }
}
```

| Champ | |
| - | - |
| `message` | Une phrase pour une personne, dans la langue de l'installation. Elle peut être reformulée : affichez-la, ne la testez pas. |
| `code` | Ce qui ne va pas, en un mot qui ne change pas. **C'est lui qu'on teste.** Tous les codes sont plus bas. |
| `doc_url` | Cette page, à l'entrée du code. Sous `/fr/` quand l'installation parle français. |

Certaines erreurs ajoutent leurs propres champs : `errors` pour une erreur de validation, `problems` pour une campagne qui n'est pas prête, `data` pour un e-mail transactionnel journalisé mais pas envoyé.

## Les statuts HTTP

| Statut | Signifie | Que faire |
| - | - | - |
| `200` `201` | Fait, ou créé. | |
| `202` | Accepté et mis en file : le travail se fait en arrière-plan (un import, un lot de plus de 100, un e-mail transactionnel). | Suivez l'`url` de la réponse, les [webhooks](https://docs.lekalao.com/fr/developers/webhooks.md), ou relisez l'e-mail par son `id`. |
| `204` | Supprimé. Pas de corps. | |
| `400` | Requête mal formée : une clé d'idempotence de plus de 255 caractères. | Corrigez l'appel. |
| `401` | Aucun jeton, ou un jeton révoqué. | Vérifiez l'en-tête `Authorization`. |
| `403` | Le jeton, le rôle de son propriétaire, l'équipe ou une clé de test ne le permet pas. | Lisez `code`. |
| `404` | Rien de cet identifiant dans cette équipe. | Vérifiez l'`id`. |
| `409` | Conflit : une campagne en cours d'envoi, une personne déjà dans l'automatisation, un appel idempotent encore en cours. | Lisez `code` ; ne le renvoyez pas tel quel. |
| `422` | Les données, ou l'opération, ont été refusées. | Lisez `code`, puis `errors` ou `message`. |
| `429` | Trop d'appels, ou le quota du mois est épuisé. | `rate_limited` : attendez `Retry-After` secondes. `monthly_quota_exceeded` : attendez le mois suivant, ou changez de formule. |
| `502` | Un e-mail transactionnel que le fournisseur a refusé, après les nouveaux essais, ou que la file d'attente n'a pas pu prendre. | Lisez `data.failure_reason`. |
| `5xx` | Un problème de Lekalao. | Réessayez plus tard, avec la même `Idempotency-Key`. |

## Les erreurs de validation

`422` `validation_error`, avec le détail champ par champ :

```json theme={null}
{
    "message": "Le champ email doit être une adresse e-mail valide.",
    "code": "validation_error",
    "doc_url": "https://docs.lekalao.com/fr/errors#validation_error",
    "errors": {
        "email": ["Le champ email doit être une adresse e-mail valide."],
        "tags.2": ["Le champ tags.2 ne doit pas dépasser 255 caractères."]
    }
}
```

Les champs d'un tableau sont nommés par leur position : `subscribers.14.email` est la 15e ligne d'un lot.

## Une adresse où rien n'arriverait

Ajouter quelqu'un de nouveau vérifie d'abord l'adresse : `POST /v1/lists/{list}/subscribers`, et `POST /v1/automations/{automation}/trigger` pour une personne qui n'est pas encore sur la liste. Une boîte jetable, ou un domaine sans serveur de messagerie, répond `422` `undeliverable_address` avec deux champs de plus :

```json theme={null}
{
    "message": "ada@gmial.com ne peut pas recevoir d'e-mail : son domaine n'a pas de serveur de messagerie. Vouliez-vous dire ada@gmail.com ?",
    "code": "undeliverable_address",
    "doc_url": "https://docs.lekalao.com/fr/errors#undeliverable_address",
    "errors": {
        "email": ["ada@gmial.com ne peut pas recevoir d'e-mail : son domaine n'a pas de serveur de messagerie. Vouliez-vous dire ada@gmail.com ?"]
    },
    "problem": "no_mail_server",
    "suggestion": "ada@gmail.com"
}
```

| Champ | Valeur |
| - | - |
| `problem` | `disposable` : une boîte jetable. `no_mail_server` : le domaine ne reçoit pas d'e-mail. |
| `suggestion` | L'adresse que la personne voulait très probablement dire, quand un domaine courant est à une ou deux touches. Sinon `null`. |

Montrez `suggestion` à la personne et laissez-la choisir : ne la substituez jamais d'office. Dans un [lot](https://docs.lekalao.com/fr/developers/subscribers.md#inscrire-en-lot), la même adresse est une ligne avec `"outcome": "failed"` et son message ; dans un import, une ligne en erreur.

## Réessayer ou non

* **Réessayez** sur `429` `rate_limited`, sur `5xx` et sur les erreurs réseau, avec un délai croissant et la même `Idempotency-Key`.
* **Lisez d'abord** un `502` d'un e-mail transactionnel : `data.failure_reason` dit si renvoyer peut marcher.
* **Ne réessayez pas** les autres `4xx` : le même appel donne la même réponse. Corrigez d'abord. Une exception : `409` `idempotency_key_in_use`, le même appel idempotent encore en cours ; réessayez un instant plus tard.

## Tous les codes

Rangés selon d'où ils viennent. Chacun a son ancre : `/fr/errors#rate_limited`.

## Toutes les routes

### `unauthenticated`

`401`. Pas d'en-tête `Authorization`, un jeton mal formé, ou révoqué. Vérifiez que le jeton entier suit `Bearer `. Voir [Authentification](https://docs.lekalao.com/fr/developers/authentication.md).

### `missing_ability`

`403`. Un jeton **Lecture** a appelé une route qui écrit. Créez un jeton **Lecture et écriture** pour cette application.

### `role_not_allowed`

`403`. Le propriétaire du jeton ne peut pas faire cela dans l'équipe : un lecteur qui écrit, un rédacteur qui envoie une campagne. Un jeton agit avec le rôle de son propriétaire, vérifié à chaque appel. Voir [Les rôles](https://docs.lekalao.com/fr/account/team.md#les-rôles).

### `team_suspended`

`403`. L'équipe est suspendue : tout appel est refusé jusqu'à ce que le service lève la suspension. Contactez le support.

### `team_access_lost`

`403`. Le propriétaire du jeton n'est plus membre de l'équipe où le jeton a été créé. Créez un jeton depuis un compte qui l'est.

### `two_factor_required`

`403`. L'équipe exige l'authentification à deux facteurs, et le propriétaire du jeton n'a ni second facteur ni clé d'accès. Dès qu'il en configure un, le jeton fonctionne de nouveau. Voir [Règles de l'équipe](https://docs.lekalao.com/fr/account/team.md#règles-de-l’équipe).

### `no_team`

`403`. Le compte n'est dans aucune équipe. Cela arrive à quelqu'un retiré de toutes ses équipes.

### `forbidden`

`403`. Refusé pour une raison qui n'a pas de code à elle. `message` dit laquelle.

### `not_found`

`404`. Aucune route à cette adresse, ou aucune ressource de cet `id` dans l'équipe du jeton. Une ressource d'une autre équipe n'est pas trouvée non plus, à dessein.

### `method_not_allowed`

`405`. La route existe, avec une autre méthode : `GET` au lieu de `POST`, par exemple.

### `conflict`

`409`. L'état de la ressource ne le permet pas. `message` dit pourquoi.

### `bad_request`

`400`. La requête n'a pas pu être lue.

### `payload_too_large`

`413`. Le corps dépasse ce que le serveur accepte. Envoyez moins de lignes par lot, ou un fichier plus petit.

### `validation_error`

`422`. Un champ manque ou est invalide. `errors` les liste, champ par champ. Voir [Les erreurs de validation](#les-erreurs-de-validation).

### `invalid_request`

`422`. Refusé pour une raison qui n'a pas de code à elle. `message` dit laquelle.

### `rate_limited`

`429`. Le jeton a dépassé ses appels de la minute (120 par défaut). Attendez les `Retry-After` secondes ; `X-RateLimit-Remaining` dit, à chaque réponse, combien d'appels restent.

### `server_error`

`500`. La faute de Lekalao. Réessayez plus tard avec la même `Idempotency-Key` ; si cela dure, donnez au support l'heure de l'appel.

### `service_unavailable`

`503`. L'installation est en maintenance. Réessayez dans quelques minutes.

## Idempotence

### `idempotency_key_too_long`

`400`. L'`Idempotency-Key` dépasse 255 caractères.

### `idempotency_key_in_use`

`409`. Un appel avec la même clé tourne encore. Réessayez un instant plus tard : vous aurez sa réponse.

### `idempotency_key_reused`

`422`. La clé a déjà servi pour une autre route ou un autre corps. Donnez à chaque opération sa propre clé.

### `idempotency_key_expired`

`422`. La clé a plus de 24 heures. Envoyez-en une nouvelle. Voir [Idempotence](https://docs.lekalao.com/fr/developers/conventions.md#idempotence).

## Clés de test

### `sandbox_cannot_send`

`403`. Une [clé de test](https://docs.lekalao.com/fr/developers/sandbox.md) a appelé une route qui existe pour écrire à de vraies personnes : envoyer une campagne, faire entrer quelqu'un dans une automatisation, renvoyer un e-mail de confirmation. Utilisez une clé réelle.

## Contacts

### `undeliverable_address`

`422`. L'adresse ne peut pas recevoir d'e-mail : une boîte jetable, ou un domaine sans serveur de messagerie. Voir [Une adresse où rien n'arriverait](#une-adresse-où-rien-n’arriverait).

### `address_suppressed`

`422`. L'adresse est sur la [liste de suppression](https://docs.lekalao.com/fr/contacts/suppression-list.md) de l'équipe : elle a rebondi définitivement, s'est plainte, ou a été bloquée à la main. L'API ne peut pas l'abonner de nouveau.

### `subscriber_limit_reached`

`422`. La formule ne contient plus d'abonnés. Changez de formule, ou nettoyez les listes. Voir [Formules](https://docs.lekalao.com/fr/account/billing.md#formules).

### `confirmation_not_needed`

`422`. `resend-confirmation` pour quelqu'un qui n'a rien à confirmer : déjà abonné, ou sur une liste sans double opt-in.

### `batch_rejected`

`422`. Aucune ligne du lot n'a pu être enregistrée. `data` donne la raison de chaque ligne, `meta` les comptes.

### `contact_not_found`

`404`. Une conversion pour une adresse qui n'est sur aucune liste de l'équipe.

### `event_count_out_of_range`

`422`. `POST /v1/events` prend un événement, ou entre 1 et 1 000 sous `events`.

## Envoi

### `sender_not_allowed`

`422`. L'adresse d'expéditeur n'est pas sur un domaine d'envoi vérifié de l'équipe, là où l'installation l'exige. Le message nomme le domaine. Voir [Domaines d'envoi](https://docs.lekalao.com/fr/deliverability/domains.md).

### `template_error`

`422`. Le modèle ne se rend pas : une balise restée ouverte, un filtre inconnu. Le message dit où.

### `content_missing`

`422`. Un e-mail transactionnel sans `template` ni `html`.

### `recipient_missing`

`422`. Un e-mail transactionnel sans `to`, d'un modèle qui n'a pas non plus de destinataires par défaut.

### `too_many_recipients`

`422`. Plus de 50 adresses dans un e-mail transactionnel, `to`, `cc` et `bcc` ensemble. Un e-mail transactionnel s'écrit à quelqu'un : envoyez-en un à chacun.

### `recipients_suppressed`

`422`. Toutes les adresses de `to` sont sur la liste de suppression. L'e-mail est journalisé `failed`, sous `data`. Le renvoyer échoue de la même façon.

### `monthly_quota_exceeded`

`429`. Les e-mails du mois de la formule sont épuisés ; chaque destinataire d'un e-mail compte, copies comprises. L'e-mail est journalisé `failed`, sous `data`. Attendez le mois suivant, ou changez de formule. Un test de campagne refusé pour cette raison répond `test_refused`.

### `sending_paused`

`422`. L'équipe ne peut pas envoyer : sa période payée s'est terminée sans paiement. L'e-mail est journalisé `failed`, sous `data`. Voir [Facturation](https://docs.lekalao.com/fr/account/billing.md).

### `provider_error`

`502`. Le fournisseur a refusé l'e-mail transactionnel à chaque essai, pendant six heures, ou une [clé de test](https://docs.lekalao.com/fr/developers/sandbox.md) a écrit à `failed@sink.lekalao.dev`. `data.failure_reason` donne le dernier mot du fournisseur.

### `queue_unavailable`

`502`. L'e-mail a été journalisé, mais la file d'attente n'a pas pu le prendre. Réessayez dans un instant avec la même `Idempotency-Key` : un `502` n'est pas gardé, l'e-mail n'est donc pas compté deux fois.

### `mail_not_kept`

`409`. Le renvoi d'un e-mail transactionnel dont le modèle ne garde ni le contenu ni les variables (codes à usage unique, liens de connexion). Envoyez un nouvel e-mail.

### `campaign_not_ready`

`422`. La campagne ne peut pas encore partir. `problems` liste ce qui manque, comme l'interface. Voir [Prête ou non](https://docs.lekalao.com/fr/campaigns/sending.md#prête-ou-non).

### `campaign_is_sending`

`409`. Une campagne en cours d'envoi ne peut pas être supprimée. Mettez-la d'abord en pause dans l'interface.

### `test_refused`

`422`. Un test de campagne qui ne peut pas partir : le domaine de l'expéditeur n'est pas vérifié (là où l'installation l'exige), toutes les adresses données sont sur la liste de suppression, l'équipe a envoyé 100 e-mails de test dans l'heure, ou le quota du mois est épuisé. `message` dit lequel.

### `automation_not_running`

`409`. L'automatisation n'est pas active, ou n'a pas de liste. Activez-la dans l'interface.

### `already_in_automation`

`409`. La personne parcourt déjà cette automatisation. La réponse porte aussi `"started": false`.

## Licences

### `licence_invalid`

`422`. `POST /v1/licences/check` : la clé ne se lit pas, ou n'est pas signée par Lekalao. La réponse porte aussi `"valid": false, "reason": "invalid"`.

### `licence_revoked`

`403`. La licence a été révoquée. La réponse porte aussi `"valid": false, "reason": "revoked"`.

## Un e-mail transactionnel qui a échoué

Un e-mail transactionnel garde la raison de son échec dans `failure_code`, avec les mêmes mots que les codes ci-dessus : `recipients_suppressed`, `monthly_quota_exceeded`, `sending_paused`, `provider_error`, `queue_unavailable`. Un de plus n'est jamais la réponse d'un appel, puisqu'il arrive plus tard : `lost`, un e-mail encore `pending` sept heures après l'appel parce que sa tâche a été perdue. Renvoyez-le. Voir [E-mails transactionnels](https://docs.lekalao.com/fr/developers/transactional.md#la-réponse).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.