Codes d'erreur

Chaque réponse d'erreur de l'API MailLand inclut un champ code avec un code d'erreur lisible par machine et un champ message avec une description lisible par l'humain.

Format des réponses d'erreurCopier le lien de la section

{
  "code": "DOMAIN_NOT_VERIFIED",
  "message": "Domain is not verified",
  "timestamp": "2026-02-18T12:35:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Certaines erreurs incluent des details supplémentaires :

{
  "code": "IP_RATE_LIMIT_EXCEEDED",
  "message": "Too many requests from this IP. Retry after 45 seconds.",
  "details": {
    "limit": 300,
    "current": 301,
    "retryAfter": 45,
    "resetAt": "2026-02-18T12:35:00Z"
  }
}

Validation de la requête (400)Copier le lien de la section

Retourné lorsque le corps de la requête, les paramètres de requête ou les en-têtes sont malformés ou manquent de champs obligatoires.

Authentification (401)Copier le lien de la section

Retourné lorsque la requête ne contient pas d'identifiants ou que les identifiants sont invalides.

Authentification à deux facteursCopier le lien de la section

Les échecs de 2FA retournent 400 INVALID_REQUEST avec un message descriptif (par ex. « Invalid code », « 2FA is already enabled »). Il n'existe pas de codes d'erreur 2FA dédiés, lisez le champ message.

Autorisation (403)Copier le lien de la section

Retourné lorsque l'utilisateur authentifié n'a pas la permission d'effectuer l'action demandée.

Introuvable (404)Copier le lien de la section

Retourné lorsque la ressource demandée n'existe pas ou appartient à un autre espace de travail.

Conflit (409)Copier le lien de la section

Retourné lorsque l'opération entre en conflit avec l'état actuel de la ressource.

Domaine et envoi (422)Copier le lien de la section

Retourné lorsque la requête est bien formée mais ne peut pas être traitée en raison de contraintes de logique métier.

Paiement requis (402)Copier le lien de la section

Retourné lorsque le solde de crédit de l'espace de travail ne peut pas couvrir l'opération demandée.

Limitation de taux (429)Copier le lien de la section

Retourné lorsque la requête dépasse les limites de taux. Inclut généralement l'en-tête Retry-After ; s'il est absent, utilisez un backoff exponentiel plutôt que de supposer qu'aucune attente n'est nécessaire.

Limites de taux de l'APICopier le lien de la section

Limites de taux d'envoi d'emailsCopier le lien de la section

Capacité de la plateforme (429)Copier le lien de la section

Ces refus signifient que c'est la plateforme, et non le quota de votre compte, qui limite actuellement les nouveaux envois. Chacun est un 429 avec un en-tête Retry-After, rien n'a été mis en file et il est sûr de réessayer la même requête. Par SMTP, ce sont des 421 Try again later: <message> transitoires. Le message est le texte anglais renvoyé par l'API.

Les e-mails déjà acceptés ne sont jamais affectés. Traitez-les comme tout autre 429 : temporisez, respectez Retry-After et réessayez. Il n'y a rien à configurer ni à mettre à niveau.

Limites par fluxCopier le lien de la section

transactional_recipient_limit_exceeded et marketing_recipient_limit_exceeded sont en 400, pas en 429 : voir la section Validation de la requête ci-dessus. BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL est également en 400 : un envoi par lot n'est pas autorisé sur un identifiant transactionnel, quelles que soient les limites de taux.

Quota et facturationCopier le lien de la section

Moteur de politiqueCopier le lien de la section

Erreurs serveur (5xx)Copier le lien de la section

Gestion des erreursCopier le lien de la section

Stratégie de nouvelle tentativeCopier le lien de la section

Lecture des en-têtes de limitation de tauxCopier le lien de la section

La plupart des réponses incluent X-RateLimit-Limit et X-RateLimit-Remaining :

Un 429 basé sur l'IP ajoute en plus :

Prochaines étapesCopier le lien de la section

• Limites de taux : niveaux de limites de taux détaillés et bonnes pratiques
• Authentification : gestion des tokens et des clés API
• Journal des modifications : suivre les changements de l'API