Codes d’erreur

Chaque erreur signalée par Mankomail porte un code stable : un identifiant court en minuscules, comme auth.unauthenticated ou llm.rate_limited. Un programme doit tester le code, jamais le message, qui est un texte technique en anglais susceptible de changer. L’interface traduit chaque code en un message dans votre langue.

Cette page explique où apparaissent les codes et présente les familles de codes en usage. Ce n’est pas une liste exhaustive de tous les codes.

Où apparaissent les codes

• Dans les réponses de l’API. Toute réponse d’erreur de l’API REST est un objet JSON avec code, message et parfois details. Le statut HTTP donne la classe de l’erreur ; le code en donne la cause précise.
• Dans les erreurs d’une exécution. Quand une étape échoue, son détail d’erreur affiche un Code, à côté du message du serveur, du nœud et du numéro de tentative. Voyez Erreurs et nouvelles tentatives.

Comment s’écrivent les codes

Tout code de l’API a la forme domaine.code : le domaine désigne la partie du produit, le code désigne la cause, par exemple webmail.sending_disabled, workflow.not_publishable, approval.not_found, wait.step_not_waiting ou api_key.scope_missing. Les codes ne contiennent que des lettres minuscules, des chiffres, _ et ., et exactement un point. Les codes génériques de la couche HTTP ont eux aussi un domaine : request.bad_request, request.not_found, request.internal_error. Traitez chaque code comme une chaîne opaque et comparez-le en entier ; le domaine sert à traiter une famille d’un coup. Voyez Erreurs pour le format complet des erreurs.

Les erreurs d’une exécution utilisent un second vocabulaire, plus court : une étape qui échoue porte un code sans domaine, comme node_invalid_param, node_timeout ou execution_timeout. Ces codes apparaissent dans le détail d’erreur d’une exécution, jamais dans le code d’une réponse de l’API.

Familles de codes

Domaine	Ce qu’il couvre	Exemples
auth	Connexion, sessions, rôles, mots de passe	auth.invalid_credentials, auth.unauthenticated, auth.forbidden, auth.too_many_attempts, auth.https_required, auth.weak_password
governance	Membres, invitations, politique de nœuds	governance.invitation_expired, governance.last_admin, governance.unknown_node_type
mailbox	Boîtes connectées et leur miroir	mailbox.not_active, mailbox.resync_window_invalid, mailbox.confirmation_mismatch
imap, smtp	Connexion d’une boîte IMAP	imap.auth_failed, imap.tls_failed, smtp.unreachable
oauth	Connexion d’un compte Google ou Microsoft	oauth.app_not_configured, oauth.access_denied, oauth.missing_refresh_token, oauth.encryption_disabled
credential	Connexions enregistrées	credential.not_found, credential.in_use, credential.encryption_disabled, credential.capability_missing
webmail	Lecture et envoi de mails dans le webmail	webmail.sending_disabled, webmail.rate_limited, webmail.message_too_large, webmail.attachment_too_large
workflow, execution	Enregistrement, publication et exécution des workflows	workflow.draft_conflict, workflow.not_published, workflow.not_publishable, execution.not_retryable, execution.version_unavailable
request	La couche HTTP elle-même : corps illisible ou trop gros, route inconnue, panne inattendue	request.bad_request, request.not_found, request.internal_error
idempotency	L’en-tête Idempotency-Key	idempotency.key_reused, idempotency.in_progress, idempotency.invalid_key
node (erreurs d’exécution)	Une étape qui ne peut pas s’exécuter ; affiché dans le détail d’une exécution, pas dans les réponses de l’API	node_missing_email, node_invalid_param, node_service_failed, node_timeout
llm	Modèles et fournisseurs d’IA	llm.provider_not_configured, llm.invalid_api_key, llm.rate_limited, llm.timeout, llm.output_truncated, llm.content_refused
integration	Services tiers (Airtable, Notion…)	integration.unauthorized, integration.missing_scopes, integration.rate_limited, integration.unavailable
google, microsoft	Actions Google et Microsoft 365 dans une étape	google.insufficient_permissions, google.not_found, microsoft.access_denied, microsoft.storage_full
tables, table	Tables, depuis l’interface et depuis les nœuds	tables.duplicate_key, tables.limit_reached, tables.invalid_csv, table.row_not_found
contacts	Carnet et signatures	contacts.invalid_csv, contacts.duplicate_signature_name
review	Revue du matin des brouillons	review.already_resolved, review.content_gone
approval	Demandes d’approbation	approval.not_found, approval.already_decided
wait	Attentes et signaux	wait.step_not_waiting, wait.deadline_invalid, wait.outcome_not_available
api_key	Clés d’API et leurs portées	api_key.scope_missing, api_key.session_required, api_key.rate_limited, api_key.scope_forbidden
analyzer	Analyseur de boîte	analyzer.llm_unavailable, analyzer.tables_required, analyzer.report_busy
templates	Templates de workflows	templates.invalid_graph, templates.forbidden_node
resource	Listes proposées pendant la configuration d’un nœud	resource.unavailable, resource.context_required
notification, dashboard	Notifications et tableaux de bord	notification.not_found, dashboard.forbidden