Erreurs

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 :

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

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 :

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

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

Erreurs de validation d’envoi

Envoyer un e-mail et Transférer un e-mail vérifient l’ensemble du message en une fois et renvoient chaque problème dans validation_errors :

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

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

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

Erreurs fréquentes et solutions

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 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 pour que l’e-mail ne soit pas envoyé deux fois.

Voir aussi