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
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. Indiquez-le au soutien
upgradeUrl	Pour les restrictions de forfait (402, 403 plan-upgrade-required) : 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 donc afficher chacun d’eux à côté du bon champ.

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 manquants, 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 touché)
403	forbidden	Authentifié, mais non autorisé : autorisation manquante, clé d’API sur un point de terminaison 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 soumis avant d’avoir validé 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 convient pas à l’état actuel, p. ex. annuler une enveloppe finalisée ou créer une session pour un destinataire qui a déjà signé
409	not-your-turn	Un signataire a soumis 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 courriel a déjà signé 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 avec la 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 téléversement qui dépasse sa limite (25 Mo pour les fichiers de modèle)
415	unsupported-media-type	Un téléversement d’un type non pris en charge
422	validation-error	Le corps, les paramètres de requête ou les variables sont invalides; consultez errors
422	idempotency-key-reused	La même Idempotency-Key a été utilisée 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 quand cet en-tête est présent
500	internal	Erreur inattendue. Une nouvelle tentative avec la même Idempotency-Key est sans risque
501	not-implemented	La fonctionnalité existe dans le schéma, mais pas encore dans les faits (p. ex. les codes par SMS)
503	converter-unavailable, billing-unavailable	Un service dont dépend l’API est temporairement indisponible; réessayez plus tard

Astuce

Relancez les erreurs 429, 5xx et les erreurs réseau avec un délai exponentiel et la même Idempotency-Key. Ne relancez pas telles quelles les autres réponses 4xx : 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})`);
  }
}