Erreurs

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.

{
  "error": {
    "code": "unknown_signer_role",
    "message": "One or more recipient roles do not match this template.",
    "details": { },
    "reference": "0190f3a2-7b6c-7e21-9a3f-2c9b1d4e5f60"
  }
}

details

Présent uniquement lorsqu'il y a quelque chose d'utile à dire. Deux cas méritent un traitement explicite :

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the required scope \"envelopes:send\".",
    "details": { "required_scope": "envelopes:send", "granted_scopes": ["templates:read"] }
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Slow down and retry after the indicated interval.",
    "details": { "retry_after": "15 minutes" }
  }
}

reference

Un UUID identifiant l'entrée de journal côté serveur pour cet échec. Il apparaît sur les erreurs que nous conservons (5xx et 422) et est absent des erreurs d'authentification ou de validation qui ne génèrent aucun journal.

Journalisez-le. Lorsque vous nous signalez un problème, citer la reference nous permet de retrouver l'échec exact en une seule recherche, au lieu de vous demander de le reproduire.

Codes d'erreur

Corriger sender_fields_incomplete

Celle-ci surprend, car la requête est parfaitement valide. Elle signifie que le modèle comporte des champs affectés à son propre rôle expéditeur (« Me ») qui sont obligatoires et vides — il n'y a donc pas de document complet à envoyer.

L'API remplit automatiquement les champs de l'expéditeur à partir de ce qui est enregistré sur le modèle ; elle ne peut pas inventer de valeurs. Corrigez-le sur le modèle, pas dans votre requête :

• donnez une valeur à ces champs expéditeur sur le modèle,
• rendez-les facultatifs, ou
• supprimez-les.

Puis relancez le même appel.

Bien gérer les erreurs

• Branchez sur error.code, jamais sur message.
• Réessayez les 5xx, 429 et erreurs réseau avec une temporisation progressive, en respectant l'en-tête Retry-After sur un 429. Ne réessayez pas les autres 4xx : la requête nous est parvenue et a été rejetée ; corrigez-la.
• Renouvelez sur 401 invalid_token en échangeant votre clé contre un nouveau jeton, puis réessayez une fois. Si vous recevez key_revoked, la clé elle-même a été révoquée : chargez la clé de remplacement au lieu de réessayer.
• Traitez quota_exceeded comme un signal d'offre, pas comme une erreur transitoire : cela se résout quand la période se réinitialise ou que l'offre évolue. Réessayer ne sert à rien et, à l'envoi, cela signifie que rien n'a été livré.
• send_failed signifie que rien n'est parti. L'enveloppe est supprimée, donc un nouvel essai en crée une nouvelle plutôt que de dupliquer une livraison.
• Journalisez reference dès qu'elle est présente.