# Erreurs

> Comment l’API Emailit signale les erreurs. Formats du corps de réponse, codes de statut HTTP et leur signification, et solutions aux messages d’erreur les plus fréquents.

L’API Emailit utilise les codes de statut HTTP pour indiquer si une requête a abouti. Les codes de la plage `2xx` signalent un succès, les codes `4xx` indiquent qu’un élément de la requête doit changer, et les codes `5xx` signalent un problème de notre côté. Cette page décrit les corps d’erreur, tous les codes de statut renvoyés par l’API et la façon de corriger les erreurs les plus fréquentes.

## Formats des réponses d’erreur

Chaque corps d’erreur est un objet JSON avec un champ `error`. Sa forme exacte dépend de l’endroit où la requête a échoué. Écrivez votre gestion des erreurs pour lire `error`, puis `message` lorsqu’il est présent, puis tout champ supplémentaire documenté par l’endpoint.

### Erreurs de requête

Les échecs d’authentification, les erreurs de droits, le JSON mal formé et les autres erreurs levées avant l’exécution d’un endpoint utilisent le format d’erreur HTTP standard :

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required"
}
```

| Champ | Description |
| --- | --- |
| `statusCode` | Le code de statut HTTP. |
| `error` | L’intitulé HTTP, comme `Unauthorized` ou `Forbidden`. |
| `message` | Ce qui s’est mal passé, en langage clair. |

### Erreurs de validation

Lorsqu’un paramètre de requête ou un champ du corps a un type incorrect, est absent ou sort de la plage autorisée, l’API rejette la requête avec `400` avant de l’exécuter et liste chaque problème dans `details` :

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error",
  "details": [
    {
      "instancePath": "/limit",
      "schemaPath": "#/properties/limit/maximum",
      "keyword": "maximum",
      "params": { "comparison": "<=", "limit": 100 },
      "message": "must be <= 100"
    }
  ]
}
```

`instancePath` désigne le champ (`/limit`, `/to`, `/attachments/0/filename`) et `message` décrit la règle non respectée. Sur quelques endpoints, comme [Envoyer un e-mail](/fr/docs/api-reference/emails/send/), ces erreurs renvoient seulement `{"error": "Bad Request"}`.

### Erreurs de ressource

Les erreurs levées par un endpoint, comme un objet introuvable ou un nom en double, renvoient `error` et souvent `message` :

```json
{
  "error": "Email not found",
  "message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}
```

Certaines erreurs ajoutent des champs qui vous aident à corriger la situation :

| Champ | Renvoyé avec | Contenu |
| --- | --- | --- |
| `existing` | `409` lorsque vous créez un domaine, une clé API, une liste de contacts, un contact ou un abonné en double | L’objet qui existe déjà, pour que vous puissiez l’utiliser à la place. |
| `usage` | `422` lorsqu’une limite du forfait est atteinte | `used`, `limit` et, pour les listes de contacts, `plan`. |
| `required_plan` | `403` avec `error: "plan_required"` | Le forfait le plus bas qui inclut la fonctionnalité, comme `pro`. |
| `code` | Certaines erreurs `403` et `422` | Un code stable, lisible par une machine, comme `unverified_workspace_recipient` ou `events_offset_too_large`. |
| `missing` | `404` de [Mettre à jour des contacts en masse](/fr/docs/api-reference/contacts/bulk/) | Les ID de contacts introuvables. |

### Erreurs de validation d’envoi

[Envoyer un e-mail](/fr/docs/api-reference/emails/send/) et [Transférer un e-mail](/fr/docs/api-reference/emails/forward/) vérifient l’ensemble du message en une fois et renvoient chaque problème dans `validation_errors` :

```json
{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: ada@example"
  ]
}
```

### Erreurs par champ

Les modèles, les campagnes et les automatisations renvoient les problèmes de validation regroupés par champ :

```json
{
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
  }
}
```

### Erreurs de limite de débit

Les réponses `429` des endpoints d’envoi indiquent la limite atteinte et le délai d’attente. Consultez [Limites de débit](/fr/docs/api-reference/rate-limits/).

```json
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 2 messages per second allowed.",
  "limit": 2,
  "current": 2,
  "retry_after": 1
}
```

## Codes de statut HTTP

| Code | Signification | Causes typiques dans l’API Emailit |
| --- | --- | --- |
| `200` | OK | La requête a abouti. Les envois, mises à jour, suppressions et lectures renvoient `200`. |
| `201` | Created | Un domaine, une clé API, une liste de contacts, un abonné, un contact, un modèle, un webhook ou un autre objet a été créé. |
| `202` | Accepted | L’import d’un rapport DMARC a été accepté pour traitement. |
| `204` | No Content | Un formulaire a été supprimé. La réponse n’a pas de corps. |
| `400` | Bad Request | JSON invalide, champ obligatoire manquant, valeur de mauvais type ou hors plage, `Idempotency-Key` invalide, ou aucun champ à mettre à jour. |
| `401` | Unauthorized | La clé API est absente, invalide, supprimée ou régénérée, ou un jeton OAuth a expiré. Consultez [Authentification](/fr/docs/api-reference/authentication/#authentication-errors). |
| `402` | Payment Required | L’espace de travail n’a pas assez de crédits pour l’envoi, la relance ou la vérification. |
| `403` | Forbidden | La portée de la clé n’autorise pas l’endpoint, une clé limitée à un domaine a envoyé depuis un autre domaine, l’espace de travail est suspendu ou pas encore vérifié, l’envoi depuis le domaine d’envoi est en pause, ou la fonctionnalité nécessite un forfait supérieur. |
| `404` | Not Found | L’objet n’existe pas dans cet espace de travail, ou un alias de modèle n’a pas de version publiée. |
| `409` | Conflict | Un objet portant le même nom ou la même adresse e-mail existe déjà, ou une requête avec la même `Idempotency-Key` est encore en cours. |
| `413` | Payload Too Large | L’e-mail composé dépasse 40 Mo, ou l’import d’un rapport DMARC dépasse 10 Mo. |
| `422` | Unprocessable Entity | La requête est valide, mais ne peut pas être traitée pour le moment : le domaine de `from` n’est pas vérifié, une pièce jointe n’a pas pu être récupérée, le statut de l’e-mail ne permet pas l’annulation ou la relance, son contenu a déjà été purgé, ou une limite du forfait a été atteinte. |
| `429` | Too Many Requests | L’espace de travail a atteint sa limite d’envoi par seconde ou quotidienne, ou la limite horaire de transferts. |
| `500` | Internal Server Error | Une erreur s’est produite de notre côté. Relancez avec un intervalle exponentiel et contactez le support si le problème persiste. |
| `503` | Service Unavailable | Panne temporaire d’une dépendance, comme le stockage des clés d’idempotence ou la base de données d’authentification. Relancez avec un intervalle exponentiel. |

## Erreurs fréquentes et solutions

| Statut | `error` | Cause | Solution |
| --- | --- | --- | --- |
| `400` | `Validation failed` | Un envoi n’a pas de `from`, de `to`, de `subject` ou de contenu, ou contient une adresse ou une pièce jointe invalide. | Corrigez chaque élément listé dans `validation_errors`. |
| `400` | `Invalid JSON in request body` (dans `message`) | Le corps n’est pas un JSON valide. | Vérifiez les guillemets et les virgules finales, et envoyez `Content-Type: application/json`. |
| `400` | `Invalid Idempotency-Key` | La clé dépasse 256 caractères ou contient d’autres caractères que des lettres, des chiffres, `-` et `_`. | Utilisez un UUID ou une valeur sûre similaire. |
| `402` | `Insufficient credits` | Les crédits sont épuisés. Chaque destinataire coûte un crédit. | Achetez des crédits ou activez la [recharge automatique](/fr/docs/billing/auto-refill/). |
| `403` | `Workspace not verified` | L’espace de travail est en mode bac à sable et un destinataire n’est pas membre de l’espace de travail. | Demandez l’[accès production](/fr/docs/workspaces/production-access/). |
| `403` | `Domain paused` | L’envoi depuis ce domaine est en pause en raison de sa [santé d’envoi](/fr/docs/deliverability/sending-health/). | Corrigez le problème de rebonds ou de plaintes, puis contactez le support. |
| `403` | `Domain not authorized` | La clé API est limitée à un autre domaine d’envoi. | Envoyez depuis le domaine de la clé ou utilisez une autre clé. |
| `403` | `plan_required` | La fonctionnalité, comme les rapports DMARC ou les filtres de webhooks, n’est pas incluse dans votre forfait. | Passez au forfait indiqué dans `required_plan`. |
| `403` | `mjml_alpha` | La requête crée ou modifie du MJML, ou appelle un endpoint MJML. MJML est en alpha et réservé à l’équipe Emailit. | Utilisez un autre éditeur ou un autre type de contenu. Consultez [Éditeurs et API MJML](/fr/docs/templates/mjml/#who-can-use-mjml). |
| `404` | `Template not found` | L’ID du modèle n’existe pas, ou l’alias n’a pas de version publiée. | [Publiez](/fr/docs/api-reference/templates/publish/) une version du modèle. |
| `409` | `… already exists` | Vous avez créé un objet avec un nom ou une adresse e-mail déjà utilisés. | Utilisez l’objet renvoyé dans `existing`, ou choisissez un autre nom. |
| `409` | `Idempotency key in progress` | Une autre requête avec la même clé n’est pas terminée. | Patientez un instant, puis relancez avec la même clé. |
| `413` | `Message too large` | L’e-mail, pièces jointes comprises, dépasse 40 Mo. | Envoyez les fichiers volumineux sous forme de liens plutôt qu’en pièces jointes. |
| `422` | `Domain not verified` | L’adresse `from` n’appartient pas à un domaine d’envoi vérifié de cet espace de travail. | [Vérifiez le domaine](/fr/docs/domains/verification/) ou modifiez `from`. |
| `422` | `Attachment error` | L’`url` d’une pièce jointe n’a pas pu être récupérée en 30 secondes, est inaccessible ou dépasse 25 Mo. | Vérifiez que l’URL est publique et que le fichier n’est pas trop volumineux, ou envoyez plutôt `content`. |
| `422` | `Cannot cancel email`, `Cannot retry email`, `Cannot update email` | Le statut de l’e-mail ne permet pas l’action, l’heure programmée est dans moins de 3 minutes, ou son contenu a été purgé. | Vérifiez le `status` de l’e-mail. Consultez chaque endpoint pour connaître les règles. |
| `422` | `Page is too deep` | Vous avez paginé au-delà de l’offset 2 500 de [Lister les événements](/fr/docs/api-reference/events/list/). | Affinez les résultats avec les filtres `type` ou `created_at`. |
| `429` | `Rate limit exceeded`, `Daily limit exceeded` | L’espace de travail a atteint sa limite d’envoi. | Attendez `retry_after` secondes. Consultez [Limites de débit](/fr/docs/api-reference/rate-limits/). |

## Relancer en toute sécurité

- Relancez les requêtes qui renvoient `429`, `500` et `503` après un délai. Utilisez l’en-tête `retry-after` lorsqu’il est présent, et un intervalle exponentiel sinon. La page [Limites de débit](/fr/docs/api-reference/rate-limits/#retry-with-backoff) contient un exemple de code.
- Ne relancez pas telles quelles les requêtes qui renvoient d’autres erreurs `4xx`. Elles échouent de la même façon tant que vous ne corrigez pas la requête.
- Lorsque vous relancez un envoi après un timeout ou une erreur `5xx`, réutilisez la même [`Idempotency-Key`](/fr/docs/api-reference/idempotency/) pour que l’e-mail ne soit pas envoyé deux fois.

## Voir aussi

  - [Authentification](/fr/docs/api-reference/authentication/): Identifiants, portées et toutes les erreurs d’authentification.
  - [Limites de débit](/fr/docs/api-reference/rate-limits/): Limites d’envoi, en-têtes et relances avec intervalle exponentiel.
  - [Idempotence](/fr/docs/api-reference/idempotency/): Relancez les envois sans envoyer deux fois.
  - [Logs de requêtes](/fr/docs/logs/request-logs/): Consultez la requête et la réponse de chaque appel API en échec.

---
Source: https://emailit.com/fr/docs/api-reference/errors/