Gå til indhold
bona fidedocs

Fejl

Fejl bruger HTTP-statuskoder og en body efter 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 Betydning
type Stabil identifikator: https://bonafidesign.com/problems/<slug>. Forgren på den (eller på slugget), ikke på title eller detail
title Kort opsummering af typen
status HTTP-statussen
detail Læsbar forklaring af netop denne forekomst
errors Valideringsproblemer: pointer (en JSON Pointer ind i anmodningens body eller ind i forespørgselsstrengen eller variablerne), message, valgfrit hint
requestId Findes også i headeren x-request-id. Oplys det til support
upgradeUrl Ved planbegrænsninger (402, 403 plan-upgrade-required): hvor man tilføjer et kort eller opgraderer

Alle valideringsproblemer i en anmodning rapporteres på én gang, så en klient kan vise hvert enkelt af dem ved siden af det rigtige felt.

Fejltyper

Sektion kaldt “Fejltyper”
Status Slug Hvornår
400 bad-request Ugyldigt formateret anmodning, f.eks. en body, der ikke er gyldig JSON
401 unauthorized Legitimationsoplysninger mangler, er ugyldigt formateret, tilbagekaldt eller udløbet
402 payment-required Et Free-workspace har fuldført sine inkluderede kuverter i denne periode; tilføj et kort, eller opgrader (testtilstand påvirkes ikke)
403 forbidden Godkendt, men ikke tilladt: en manglende tilladelse, en API-nøgle på et slutpunkt kun til dashboardet, en anmodning på tværs af websteder
403 plan-upgrade-required Funktionen indgår ikke i workspacets plan
403 verification-required En underskriver indsendte, før vedkommende havde verificeret sin engangskode
404 not-found Ressourcen findes ikke i din organisation, eller ruten findes ikke
409 invalid-state Handlingen passer ikke til den aktuelle tilstand, f.eks. annullering af en fuldført kuvert eller oprettelse af en session til en modtager, der har underskrevet
409 not-your-turn En underskriver indsendte, før tidligere grupper i rækkefølgen var færdige
409 document-mismatch Dokumentet er ændret, siden det blev vist for underskriveren (viewedDocumentHash)
409 already-signed E-mailadressen har allerede underskrevet dette permanente link
409 in-use Sletning af en skabelon, som kuverter eller underskriftslinks bruger
409 no-draft Udgivelse af en skabelon, der ikke har nogen kladde
409 idempotency-in-progress En anmodning med samme Idempotency-Key kører stadig
409 conflict Andre konflikter
410 gone En signeringssession, der allerede er brugt eller er udløbet
413 payload-too-large En upload over grænsen (25 MB for skabelonfiler)
415 unsupported-media-type En upload af en type, der ikke understøttes
422 validation-error Body, forespørgselsstreng eller variabler er ugyldige; se errors
422 idempotency-key-reused Den samme Idempotency-Key blev brugt med en anden anmodning
422 conversion-failed Et Word-dokument kunne ikke konverteres
429 rate-limited For mange anmodninger; vent i Retry-After sekunder, når headeren findes
500 internal Uventet fejl. Sikkert at forsøge igen med samme Idempotency-Key
501 not-implemented Funktionen findes i skemaet, men endnu ikke i praksis (f.eks. sms-koder)
503 converter-unavailable, billing-unavailable En afhængighed er midlertidigt utilgængelig; prøv igen senere

Håndtering af fejl

Sektion kaldt “Håndtering af fejl”
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})`);
  }
}