Erreurs - Lekalao

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

422 Unprocessable Content

{
    "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, 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 :

{
    "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 :

{
    "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, 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.

`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.

`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.

`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.

`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.

Clés de test

`sandbox_cannot_send`

403. Une clé de test 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.

`address_suppressed`

422. L’adresse est sur la liste de suppression 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.

`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.

`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.

`provider_error`

502. Le fournisseur a refusé l’e-mail transactionnel à chaque essai, pendant six heures, ou une clé de test 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.

`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.

​Les statuts HTTP

​Les erreurs de validation

​Une adresse où rien n’arriverait

​Réessayer ou non

​Tous les codes

​Toutes les routes

​unauthenticated

​missing_ability

​role_not_allowed

​team_suspended

​team_access_lost

​two_factor_required

​no_team

​forbidden

​not_found

​method_not_allowed

​conflict

​bad_request

​payload_too_large

​validation_error

​invalid_request

​rate_limited

​server_error

​service_unavailable

​Idempotence

​idempotency_key_too_long

​idempotency_key_in_use

​idempotency_key_reused

​idempotency_key_expired

​Clés de test

​sandbox_cannot_send

​Contacts

​undeliverable_address

​address_suppressed

​subscriber_limit_reached

​confirmation_not_needed

​batch_rejected

​contact_not_found

​event_count_out_of_range

​Envoi

​sender_not_allowed

​template_error

​content_missing

​recipient_missing

​too_many_recipients

​recipients_suppressed

​monthly_quota_exceeded

​sending_paused

​provider_error

​queue_unavailable

​mail_not_kept

​campaign_not_ready

​campaign_is_sending

​test_refused

​automation_not_running

​already_in_automation

​Licences

​licence_invalid

​licence_revoked

​Un e-mail transactionnel qui a échoué