Fel

Fel använder HTTP-statuskoder och en brödtext enligt RFC 9457 med 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"
}

Medlem	Betydelse
`type`	Stabil identifierare: `https://bonafidesign.com/problems/<slug>`. Förgrena på den (eller på slugen), inte på `title` eller `detail`
`title`	Kort sammanfattning av typen
`status`	HTTP-statusen
`detail`	Läsbar förklaring av just den här förekomsten
`errors`	Valideringsproblem: `pointer` (en JSON Pointer in i begärans brödtext, eller in i frågesträngen eller variablerna), `message`, valfritt `hint`
`requestId`	Finns också i rubriken `x-request-id`. Ange det till supporten
`upgradeUrl`	Vid planspärrar (`402`, `403 plan-upgrade-required`): var man lägger till ett kort eller uppgraderar

Alla valideringsproblem i en begäran rapporteras på en gång, så att en klient kan visa vart och ett av dem bredvid rätt fält.

Feltyper

Status	Slug	När
400	`bad-request`	Felformaterad begäran, till exempel en brödtext som inte är giltig JSON
401	`unauthorized`	Autentiseringsuppgifter saknas, är felformaterade, återkallade eller har gått ut
402	`payment-required`	En arbetsyta på Free har slutfört sina inkluderade kuvert för perioden; lägg till ett kort eller uppgradera (testläget påverkas inte)
403	`forbidden`	Autentiserad men inte tillåten: en behörighet som saknas, en API-nyckel på en slutpunkt som bara är för instrumentpanelen, en begäran mellan webbplatser
403	`plan-upgrade-required`	Funktionen ingår inte i arbetsytans plan
403	`verification-required`	En undertecknare skickade in innan hen hade verifierat sin engångskod
404	`not-found`	Resursen finns inte i din organisation, eller vägen finns inte
409	`invalid-state`	Åtgärden passar inte det aktuella tillståndet, t.ex. att makulera ett slutfört kuvert eller skapa en session för en mottagare som har signerat
409	`not-your-turn`	En undertecknare skickade in innan tidigare dirigeringsgrupper var klara
409	`document-mismatch`	Dokumentet har ändrats sedan det visades för undertecknaren (`viewedDocumentHash`)
409	`already-signed`	E-postadressen har redan signerat den här permanenta länken
409	`in-use`	Borttagning av en mall som används av kuvert eller signeringslänkar
409	`no-draft`	Publicering av en mall som saknar utkast
409	`idempotency-in-progress`	En begäran med samma `Idempotency-Key` körs fortfarande
409	`conflict`	Andra konflikter
410	`gone`	En signeringssession som redan har använts eller har gått ut
413	`payload-too-large`	En uppladdning över sin gräns (25 MB för mallfiler)
415	`unsupported-media-type`	En uppladdning av en typ som inte stöds
422	`validation-error`	Brödtexten, frågesträngen eller variablerna är ogiltiga; se `errors`
422	`idempotency-key-reused`	Samma `Idempotency-Key` användes med en annan begäran
422	`conversion-failed`	Ett Word-dokument kunde inte konverteras
429	`rate-limited`	För många begäranden; vänta i `Retry-After` sekunder när rubriken finns
500	`internal`	Oväntat fel. Säkert att försöka igen med samma `Idempotency-Key`
501	`not-implemented`	Funktionen finns i schemat men inte än (t.ex. sms-koder)
503	`converter-unavailable`, `billing-unavailable`	Ett beroende är tillfälligt otillgängligt; försök igen senare

Hantera fel

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})`);
  }
}