Erreurs

Les erreurs utilisent les codes d’état HTTP et un corps conforme à la RFC 9457, avec Content-Type: application/problem+json :

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/recipients/0/email", "message": "Invalid email address" },
    { "pointer": "/recipients", "message": "Missing recipient for role 'company'." },
    { "pointer": "/recipients/1/role", "message": "Unknown role 'cfo'.", "hint": "Template roles: client, company" }
  ],
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Membre	Signification
type	Identifiant stable : https://bonafidesign.com/problems/<slug>. Basez votre logique sur cette valeur (ou sur le slug), et non sur title ou detail
title	Bref résumé du type
status	Le code d’état HTTP
detail	Explication lisible de cette occurrence précise
errors	Problèmes de validation : pointer (un JSON Pointer vers le corps de la requête, ou vers les paramètres de requête ou les variables), message, hint facultatif
requestId	Figure aussi dans l’en-tête x-request-id. Communiquez-le au support
upgradeUrl	En cas de limite de forfait (402, 403 plan-upgrade-required) : l’adresse où ajouter une carte ou changer de forfait

Tous les problèmes de validation d’une requête sont signalés en une seule fois : un client peut ainsi afficher chacun d’eux à côté du champ concerné.

Types d’erreurs

Code	Slug	Quand
400	bad-request	Requête mal formée, par exemple un corps qui n’est pas du JSON valide
401	unauthorized	Identifiants absents, mal formés, révoqués ou expirés
402	payment-required	Un espace de travail Free a finalisé ses enveloppes incluses pour la période ; ajoutez une carte ou changez de forfait (le mode test n’est pas concerné)
403	forbidden	Authentifié mais non autorisé : autorisation manquante, clé API utilisée sur un endpoint réservé au tableau de bord, requête intersite
403	plan-upgrade-required	La fonctionnalité n’est pas incluse dans le forfait de l’espace de travail
403	verification-required	Un signataire a validé avant de confirmer son code à usage unique
404	not-found	La ressource n’existe pas dans votre organisation, ou la route n’existe pas
409	invalid-state	L’action ne correspond pas à l’état actuel, par exemple l’annulation d’une enveloppe finalisée ou la création d’une session pour un destinataire qui a déjà signé
409	not-your-turn	Un signataire a validé avant que les groupes d’acheminement précédents aient terminé
409	document-mismatch	Le document a changé depuis qu’il a été présenté au signataire (viewedDocumentHash)
409	already-signed	L’adresse e-mail a déjà signé via ce lien permanent
409	in-use	Suppression d’un modèle utilisé par des enveloppes ou des liens de signature
409	no-draft	Publication d’un modèle qui n’a pas de brouillon
409	idempotency-in-progress	Une requête portant le même Idempotency-Key est toujours en cours
409	conflict	Autres conflits
410	gone	Une session de signature déjà utilisée ou expirée
413	payload-too-large	Un fichier importé dépasse sa limite (25 Mo pour les fichiers de modèle)
415	unsupported-media-type	Un fichier importé d’un type non pris en charge
422	validation-error	Le corps, les paramètres de requête ou les variables sont invalides ; voir errors
422	idempotency-key-reused	Le même Idempotency-Key a été utilisé avec une requête différente
422	conversion-failed	Un document Word n’a pas pu être converti
429	rate-limited	Trop de requêtes ; attendez le nombre de secondes indiqué par Retry-After lorsqu’il est présent
500	internal	Erreur inattendue. Peut être relancée sans risque avec le même Idempotency-Key
501	not-implemented	La fonctionnalité existe dans le schéma mais pas encore dans les faits (par exemple les codes SMS)
503	converter-unavailable, billing-unavailable	Une dépendance est temporairement indisponible ; réessayez plus tard

Astuce

Relancez les erreurs 429, 5xx et réseau avec un délai exponentiel et le même Idempotency-Key. Ne relancez pas les autres réponses 4xx à l’identique : corrigez d’abord la requête.

Gérer les erreurs

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', { method: 'POST', headers, body });
if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  const slug = problem.type.split('/').pop();
  if (slug === 'validation-error') {
    for (const e of problem.errors) form.setError(e.pointer, e.message);
  } else if (slug === 'payment-required') {
    showUpgrade(problem.upgradeUrl);
  } else {
    throw new Error(`${problem.title} (${problem.requestId})`);
  }
}