Codes d’erreur
Chaque réponse d’erreur a la même forme. docs_url pointe vers l’entrée correspondante de cette
page.
{ "error": { "code": "invalid_template_params", "message": "Invalid template parameters. email: Invalid email address.", "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params", "details": { "issues": [{ "param": "email", "code": "invalid_email", "message": "Invalid email address." }] } }}Les réponses 429 contiennent en plus un en-tête Retry-After exprimé en secondes. Les SDK lèvent
ces erreurs sous forme de sous-classes typées de FrontmailError – voir
Gestion des erreurs.
bad_request HTTP 400
Signification : La requête n’a pas pu être comprise (mauvais type de contenu, JSON illisible, méthode non prise en charge).
Comment corriger : Envoyez Content-Type: application/json (ou multipart/form-data pour /v1/send-form) et un corps valide. Les SDK s’en chargent pour vous.
invalid_body HTTP 400
Signification : Le JSON est valide mais ne respecte pas le schéma, p. ex. un template_id manquant ou un champ du mauvais type. details liste les champs en cause.
Comment corriger : Comparez le corps avec la référence de l’API REST et corrigez les champs listés dans details.
invalid_idempotency_key HTTP 400
Signification : L’en-tête Idempotency-Key est vide ou dépasse 255 caractères.
Comment corriger : Utilisez un UUID ou une autre chaîne unique de 255 caractères maximum. Les SDK en génèrent une par envoi logique.
unauthorized HTTP 401
Signification : Aucune clé n’a été fournie, ou la clé ne correspond à aucune organisation.
Comment corriger : Transmettez la clé publique via user_id / X-Frontmail-Public-Key, ou la clé privée via Authorization: Bearer sk_….
invalid_public_key HTTP 401
Signification : La clé publique n’existe pas ou a été renouvelée.
Comment corriger : Copiez la clé publique actuelle depuis Sécurité → Clé publique dans le tableau de bord. Après un renouvellement, redéployez votre site avec la nouvelle clé.
invalid_private_key HTTP 401
Signification : La clé privée est inconnue ou a été révoquée.
Comment corriger : Créez une nouvelle clé privée dans Sécurité → Clés privées et mettez à jour le secret dans l’environnement de votre serveur.
insufficient_credits HTTP 402
Signification : Votre organisation n’a plus de crédits et utilise le mode reject. Dans le mode par défaut hold, vous obtenez à la place 202 avec status: "held" – sauf si la file d’attente des e-mails retenus est pleine (details.reason: "hold_queue_full", avec held et limit).
Comment corriger : Achetez un pack de crédits, activez la recharge automatique, passez à un forfait supérieur ou choisissez Retenir les e-mails dans Sécurité → Quand vous n’avez plus de crédits. Pour hold_queue_full, libérez ou supprimez également des e-mails retenus. Voir File d’attente des e-mails retenus.
forbidden HTTP 403
Signification : La clé ou l’utilisateur n’est pas autorisé à effectuer cette action.
Comment corriger : Vérifiez le rôle du membre ou utilisez une clé privée pour les endpoints côté serveur.
origin_not_allowed HTTP 403
Signification : La requête provient d’un Origin absent de votre liste d’origines autorisées – ou elle n’a pas du tout d’Origin/Referer (serveur, curl, application native) et Autoriser les applications mobiles est désactivé. Dans ce cas, details.reason vaut no_origin.
Comment corriger : Ajoutez le domaine (p. ex. example.com ou *.example.com) dans Sécurité → Sites autorisés. Le développement local nécessite aussi localhost. Pour les applications natives, activez Autoriser les applications mobiles ; sur un serveur, utilisez une clé privée au lieu de la clé publique.
captcha_required HTTP 403
Signification : Le modèle exige Turnstile et la requête ne contenait aucun jeton.
Comment corriger : Affichez le widget Turnstile (le composant FrontmailForm pour React/Vue/Svelte s’en charge) ou transmettez turnstile_token. Les appels côté serveur avec une clé privée ne sont pas soumis à ce contrôle.
captcha_failed HTTP 403
Signification : Cloudflare a refusé le jeton Turnstile – il est invalide, expiré (un jeton vit environ 5 minutes) ou a déjà été utilisé. Avec details.reason: "hostname_mismatch", le widget a été résolu sur un autre nom d’hôte que celui d’où provient la requête.
Comment corriger : Réinitialisez le widget et laissez l’utilisateur le résoudre de nouveau. Ne réutilisez jamais un jeton pour plusieurs envois. Pour hostname_mismatch, ajoutez tous les noms d’hôte de votre site (p. ex. example.com et www.example.com) à votre widget Turnstile dans Cloudflare. Voir Turnstile.
captcha_not_configured HTTP 403
Signification : Le modèle exige Turnstile, mais votre organisation n’a pas ajouté ses propres clés Turnstile : les requêtes provenant de sites web ne peuvent donc pas être vérifiées. En production, les clés de test Cloudflare (1x…, toujours valides) sont également refusées (details.reason: "test_secret").
Comment corriger : Créez un widget Turnstile gratuit dans votre compte Cloudflare et ajoutez sa clé de site et sa clé secrète dans Sécurité → Protection contre les bots (Turnstile). Ou désactivez Exiger un CAPTCHA (Turnstile) sur le modèle. Voir Turnstile.
headless_blocked HTTP 403
Signification : blockHeadless est activé et la requête semble provenir d’un navigateur headless.
Comment corriger : Comportement normal pour les bots. Si un véritable utilisateur est concerné, désactivez blockHeadless dans l’init du SDK ou Bloquer les navigateurs headless dans Sécurité → Protection contre les abus.
recipient_blocked HTTP 403
Signification : Un destinataire ou la variable surveillée correspond à une entrée de votre liste de blocage.
Comment corriger : Retirez l’entrée de Sécurité → Liste de blocage si elle a été ajoutée par erreur.
private_key_required HTTP 403
Signification : L’endpoint (batch, historique, modèles) ou le réglage de l’organisation exige une clé privée.
Comment corriger : Appelez-le depuis votre serveur avec Authorization: Bearer sk_… – ne livrez jamais une clé privée au navigateur.
private_key_in_browser HTTP 403
Signification : Une clé privée (Authorization: Bearer sk_… ou accessToken) a été envoyée avec un en-tête Origin, c’est-à-dire depuis une page web, où n’importe quel visiteur peut la lire. Les clés privées sont des identifiants côté serveur.
Comment corriger : Utilisez la clé publique dans le navigateur. Gardez la clé privée sur votre serveur. Si vous en avez vraiment besoin dans un navigateur (outil interne), activez Autoriser les clés privées dans les navigateurs dans Sécurité – et renouvelez la clé si elle a été publique à un moment donné.
email_not_verified HTTP 403
Signification : Le propriétaire du compte n’a pas encore vérifié son adresse e-mail. Un compte non vérifié peut parcourir le tableau de bord, mais pas envoyer.
Comment corriger : Cliquez sur le lien de l’e-mail de vérification, ou renvoyez-le depuis la bannière du tableau de bord.
organization_suspended HTTP 403
Signification : L’organisation a été suspendue, généralement pour abus ou contestation de paiement.
Comment corriger : Contactez support@frontmail.dev depuis l’adresse du propriétaire.
plan_limit_reached HTTP 403
Signification : Une limite du forfait autre que les crédits a été atteinte – nombre de modèles, d’utilisateurs, ou une fonctionnalité non incluse dans votre forfait. Les éléments gelés après un passage à un forfait inférieur renvoient aussi cette erreur – pour les envois comme pour Renvoyer dans le tableau de bord (details.reason: "template_frozen").
Comment corriger : Passez à un forfait supérieur – les modèles et membres gelés sont dégelés automatiquement – ou supprimez des modèles / révoquez des invitations en attente pour libérer de la place. Voir Forfaits et Changement de forfait.
dynamic_recipient_not_allowed HTTP 403
Signification : Un champ destinataire (To/CC/BCC) est construit à partir d’un paramètre, mais le modèle n’autorise pas les destinataires dynamiques. Cela vous évite d’être utilisé comme relais ouvert.
Comment corriger : Activez Autoriser un destinataire dynamique dans les paramètres du modèle (Paramètres → Protection) uniquement si vous en avez vraiment besoin et que Turnstile et les origines autorisées sont activés.
dynamic_recipient_requires_captcha HTTP 403
Signification : Le modèle tire son destinataire des paramètres et la requête utilise la clé publique, mais le modèle n’exige pas de CAPTCHA. Sans lui, quiconque copie votre clé publique pourrait envoyer votre modèle à n’importe quelle adresse.
Comment corriger : Ajoutez vos clés Cloudflare Turnstile dans Sécurité → Protection contre les bots et activez Exiger un CAPTCHA pour le modèle – ou envoyez ce modèle depuis votre serveur avec une clé privée. Voir Liens autorisés et verrouillage du contenu.
dynamic_field_not_allowed HTTP 403
Signification : Un champ d’expéditeur est construit à partir des paramètres et la requête utilise la clé publique : l’adresse d’expéditeur ne peut jamais l’être, et pour les modèles à destinataire dynamique, le nom d’expéditeur et le Reply-To non plus. details.fields les liste.
Comment corriger : Utilisez des valeurs fixes dans le modèle (l’adresse du visiteur n’a sa place dans le Reply-To que si le destinataire est fixe, p. ex. un formulaire de contact) – ou envoyez depuis votre serveur avec une clé privée.
link_not_allowed HTTP 403
Signification : L’e-mail généré contient un lien vers un domaine hors de votre liste de liens autorisés. Vérifié pour les envois par clé publique vers des modèles à destinataire dynamique, pour les réponses automatiques et pour les modèles avec N’autoriser que les liens vers des domaines autorisés. details.hosts liste les domaines en cause (jamais l’URL complète).
Comment corriger : Ajoutez le domaine dans Sécurité → Domaines de liens autorisés, écrivez le lien directement dans le modèle, ou retirez-le des paramètres. Voir Liens autorisés et verrouillage du contenu.
attachments_not_allowed HTTP 403
Signification : La requête contient des pièces jointes dynamiques, mais le modèle ne les autorise pas, votre forfait n’inclut pas de pièces jointes (Free), ou le type de fichier est bloqué (exécutables, scripts, images disque, HTML/SVG, fichiers Office avec macros). POST /v1/uploads avec la clé publique nécessite aussi au moins un modèle qui autorise les pièces jointes.
Comment corriger : Activez Autoriser les pièces jointes du formulaire dans les paramètres du modèle et vérifiez que votre forfait inclut les pièces jointes.
not_found HTTP 404
Signification : L’URL ne correspond à aucun endpoint.
Comment corriger : Vérifiez le chemin et le préfixe /v1.
service_not_found HTTP 404
Signification : Le service_id n’existe pas dans l’organisation de cette clé, ou aucun service par défaut n’est défini.
Comment corriger : Copiez l’ID depuis Services d’envoi, ou définissez un service par défaut.
template_not_found HTTP 404
Signification : Le template_id n’existe pas dans l’organisation de cette clé.
Comment corriger : Copiez l’ID du modèle depuis Modèles. Les clés d’une autre organisation ne voient pas le modèle.
message_not_found HTTP 404
Signification : Le message n’existe pas, est plus ancien que la durée de conservation de votre historique, ou le jeton de statut ne correspond pas.
Comment corriger : Utilisez le message_id et le status_token de la réponse à l’envoi.
conflict HTTP 409
Signification : La ressource a été modifiée simultanément ou se trouve dans un état qui ne permet pas l’opération (p. ex. libérer un message déjà envoyé). Avec details.reason: "subscription_not_active", un changement de forfait a été refusé parce que l’abonnement a une facture impayée.
Comment corriger : Rechargez la ressource et réessayez. Pour subscription_not_active, réglez la facture en attente (Facturation → Forfait → Gérer cartes et factures), puis changez de forfait.
idempotency_conflict HTTP 409
Signification : La même Idempotency-Key a été utilisée dans les 24 heures avec un corps de requête différent.
Comment corriger : Générez une nouvelle clé pour chaque nouvel envoi logique. Ne réutilisez une clé que pour retenter la même requête à l’identique.
payload_too_large HTTP 413
Signification : Le corps de la requête dépasse la taille maximale.
Comment corriger : Passez les fichiers volumineux par les téléversements et gardez des paramètres légers.
attachment_too_large HTTP 413
Signification : La taille totale des pièces jointes d’une requête dépasse la limite de votre forfait.
Comment corriger : Compressez les fichiers, envoyez plutôt un lien, ou passez à un forfait supérieur. Voir Forfaits.
invalid_template_params HTTP 422
Signification : Les paramètres ne respectent pas le schéma du modèle – un paramètre obligatoire manque, une valeur a le mauvais type ou enfreint une règle (longueur, plage, motif, enum). En mode strict, les paramètres inconnus échouent aussi. Les envois par clé publique vers des modèles à destinataire dynamique refusent en outre les paramètres HTML et les valeurs de plus de 500 caractères (details.reason: "content_locked"). details contient une entrée par champ.
Comment corriger : Corrigez les champs listés dans details. Générez des types avec npx frontmail types pour détecter ces erreurs dès la compilation.
translation_not_configured HTTP 422
Signification : Une traduction automatique a été demandée, mais l’organisation n’a pas de clé API pour un fournisseur de traduction (ou pas pour celui demandé).
Comment corriger : Ajoutez votre propre clé OpenAI, Anthropic, Gemini ou DeepL dans Paramètres → Traduction automatique. Voir Traductions des modèles.
translation_invalid HTTP 422
Signification : Le fournisseur a renvoyé une traduction qui modifie la structure du modèle – une expression Handlebars, un lien ou une adresse d’image manque ou diffère. Rien n’a été enregistré.
Comment corriger : Réessayez, avec un autre fournisseur ou modèle, ou traduisez la variante manuellement.
translation_provider_auth HTTP 422
Signification : Le fournisseur de traduction a refusé la clé API de l’organisation (invalide, expirée ou sans accès au modèle).
Comment corriger : Remplacez la clé dans Paramètres → Traduction automatique ou choisissez un modèle auquel votre compte a accès.
template_render_failed HTTP 422
Signification : Handlebars n’a pas pu générer le rendu du modèle avec ces paramètres (p. ex. #each sur autre chose qu’une liste, un helper inconnu).
Comment corriger : Ouvrez l’éditeur de modèle – le panneau des vérifications indique le problème. Testez avec les mêmes paramètres dans l’aperçu.
invalid_recipient HTTP 422
Signification : Après le rendu, une valeur To/CC/BCC/Reply-To n’est pas une adresse e-mail valide, ou To est vide.
Comment corriger : Vérifiez les champs destinataires du modèle et les paramètres qu’ils utilisent.
sender_not_configured HTTP 422
Signification : L’e-mail n’a pas d’adresse d’expéditeur : le modèle n’en a pas et le service d’envoi n’a pas d’expéditeur par défaut (ni de compte connecté ou de nom d’utilisateur SMTP en forme d’adresse e-mail à utiliser à la place). Renvoyé par les envois de test depuis le tableau de bord.
Comment corriger : Définissez l’e-mail d’expéditeur par défaut dans les paramètres du service (Services d’envoi → service) ou un e-mail d’expéditeur dans les paramètres du modèle. Avec Amazon SES et la plupart des API, l’adresse doit être une identité vérifiée.
rate_limited HTTP 429
Signification : Trop de requêtes pour votre forfait, votre IP, votre clé ou votre réglage limitRate – ou la détection d’anomalies a ralenti votre organisation. details.scope: "recipient" signifie que le destinataire a déjà reçu le maximum quotidien d’e-mails à destinataire dynamique (Sécurité → E-mails par destinataire et par jour) ; details.scope: "uploadbytes" signifie que le budget quotidien de téléversements par clé publique est épuisé.
Comment corriger : Attendez Retry-After secondes (les SDK le font automatiquement). Pour les envois en masse, utilisez /v1/send-batch. Voir Rate limits.
test_send_limit HTTP 429
Signification : Vous avez utilisé tous les envois de test gratuits de l’éditeur de modèle pour aujourd’hui (20 par jour).
Comment corriger : Attendez demain (UTC) ou envoyez un vrai message via l’API.
recipient_suppressed HTTP 451
Signification : Le destinataire est sur votre liste de suppression suite à un rebond définitif, une plainte ou un ajout manuel. Aucun crédit n’est consommé.
Comment corriger : Ne retirez l’adresse de la Liste de suppression que si vous êtes sûr qu’elle est valide et que la personne souhaite recevoir vos e-mails.
internal_error HTTP 500
Signification : Une erreur s’est produite de notre côté.
Comment corriger : Réessayez avec la même Idempotency-Key (sans risque, aucun doublon). Si le problème persiste, consultez status.frontmail.dev et contactez le support avec l’ID de la requête.
provider_error HTTP 502
Signification : Le fournisseur d’e-mail a renvoyé une erreur inattendue lors d’une opération synchrone, comme le test d’un service.
Comment corriger : Ouvrez le service dans le tableau de bord pour voir le message du fournisseur. Voir les guides des fournisseurs.
translation_provider_error HTTP 502
Signification : Le fournisseur de traduction a échoué ou n’a pas répondu à temps. details.status contient son statut HTTP.
Comment corriger : Réessayez plus tard. La cause la plus fréquente est une limite de débit ou le quota de votre compte chez le fournisseur.
Erreurs côté client (SDK)
Ces codes sont générés par les SDK, sans réponse de l’API. L’erreur a le statut 0.
network_error SDK
Signification : La requête n’a jamais reçu de réponse HTTP – hors ligne, échec DNS, blocage par une extension ou par une règle CORS/CSP. Déjà retentée avec backoff.
Comment corriger : Vérifiez la connexion et votre Content-Security-Policy (connect-src https://api.frontmail.dev). Invitez l’utilisateur à réessayer.
timeout SDK
Signification : Une tentative a dépassé timeoutMs (15 s par défaut) et toutes les nouvelles tentatives ont aussi expiré.
Comment corriger : Vous pouvez réessayer sans risque – le SDK réutilise la clé d’idempotence, aucun doublon n’est envoyé.
aborted SDK
Signification : L’AbortSignal passé dans options.signal a été déclenché.
Comment corriger : Rien à corriger – en général, le composant a été démonté ou l’utilisateur a quitté la page.
invalid_response SDK
Signification : Le serveur a répondu autre chose qu’une réponse JSON Frontmail – typiquement un proxy, un portail captif ou un mauvais apiUrl.
Comment corriger : Vérifiez l’option apiUrl et tout proxy entre le client et api.frontmail.dev.
not_initialized SDK
Signification : send() a été appelé avant init() et sans clé dans les options de l’appel.
Comment corriger : Appelez init({ publicKey }) une fois au démarrage, ou passez la clé en dernier argument.
private_key_in_browser SDK
Signification : Une clé privée (privateKey, ou accessToken dans @frontmail/emailjs-compat) a été configurée dans du code exécuté dans un navigateur, ou @frontmail/node a été intégré dans une page. Tout visiteur de la page pourrait copier la clé et lire votre historique de messages.
Comment corriger : Utilisez la clé publique (pk_…) dans le navigateur et gardez la clé privée sur votre serveur. Renouvelez la clé privée si elle a déjà été déployée sur une page. Pour un outil interne sur des machines de confiance uniquement, passez dangerouslyAllowPrivateKeyInBrowser: true.