Erreurs

Toutes les erreurs que l'API de signature électronique peut renvoyer, avec un code lisible par machine et stable sur lequel vous appuyer.

Toutes les réponses d'erreur ont la même forme. Lisez error.code : c'est une valeur stable et lisible par machine. Le message est destiné aux humains et peut changer à tout moment, donc ne vous basez jamais sur le texte du message.

Forme de l'erreur

{
  "error": {
    "code": "unknown_signer_role",
    "message": "One or more recipient roles do not match this template.",
    "details": { }
  }
}

details est facultatif et, lorsqu'il est présent, porte un contexte structuré sur l'erreur.

Codes d'erreur

HTTP	`error.code`	Signification
`401`	`missing_api_key`	Pas d'en-tête `X-API-Key` sur la requête de jeton.
`401`	`invalid_api_key`	La clé est inconnue, révoquée, expirée ou n'est pas de mode réel.
`401`	`missing_token`	Aucun jeton `Authorization: Bearer` n'a été envoyé.
`401`	`invalid_token`	Le jeton est mal formé ou expiré. Demandez-en un nouveau.
`401`	`key_revoked`	La clé derrière ce jeton a été révoquée ou renouvelée — ses jetons ne fonctionnent plus.
`403`	`insufficient_scope`	La clé ne porte pas le scope requis par cet endpoint.
`403`	`forbidden`	Le propriétaire de la clé n'a pas la permission sous-jacente, ou l'accès à l'API n'est pas dans votre plan.
`403`	`signing_links_disabled`	L'enveloppe ne partage pas les liens de signature avec l'expéditeur.
`402`	`quota_exceeded`	Plus de demandes de signature par API disponibles (à l'envoi).
`403`	`quota_exceeded`	Une limite de ressource a été atteinte (par exemple, celle des contacts).
`404`	`template_not_found`	Aucun modèle avec cet id n'existe dans votre entreprise.
`404`	`envelope_not_found`	Aucune enveloppe avec cet id n'existe dans votre entreprise.
`404`	`webhook_not_found`	Aucun abonnement webhook avec cet id n'existe dans votre entreprise.
`422`	`unknown_signer_role`	Un rôle de destinataire ne correspond pas au modèle, ou un rôle verrouillé a été fourni.
`422`	`sender_not_found`	`sender_email` n'est pas un utilisateur actif disposant d'un siège de signature électronique dans votre entreprise.
`422`	`validation_failed`	Le corps de la requête est mal formé ou un champ requis manque.
`429`	`rate_limited`	Trop de requêtes — patientez puis réessayez.
`5xx`	`send_failed`	L'enveloppe a été créée mais n'a pas pu être envoyée, elle a donc été supprimée. Rien n'a été livré.
`500`	`internal_error`	Un problème est survenu de notre côté. Peut être réessayé.

Pourquoi certaines erreurs sont volontairement vagues

Sur l'endpoint de jeton, « clé inexistante », « révoquée », « expirée » et « pas en mode réel » renvoient toutes le même corps 401. De même, un modèle dans une autre entreprise et un modèle qui n'existe pas renvoient tous deux 404 template_not_found. C'est volontaire : une erreur plus précise permettrait de sonder quels ids ou quelles clés existent.

Bien gérer les erreurs

Basez-vous sur error.code, jamais sur message.
Réessayez les 5xx, 429 et erreurs réseau avec un délai progressif. Ne réessayez pas les 4xx — la requête nous est parvenue et a été rejetée ; corrigez plutôt la requête.
Rafraîchissez sur 401 invalid_token en échangeant votre clé contre un nouveau jeton. Si vous recevez key_revoked, la clé elle-même a été révoquée — créez-en une nouvelle dans Paramètres → Clés d'API.
Traitez quota_exceeded comme un signal de plan, pas comme une erreur transitoire : il se résout au réinitialisation de la période ou à la montée en gamme de votre plan.

Codes d'erreur

Bien gérer les erreurs

Sur cette page