Ga naar inhoud
bona fidedocs

Fouten

Fouten gebruiken HTTP-statuscodes en een body volgens RFC 9457 met 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"
}
Lid Betekenis
type Stabiele identifier: https://bonafidesign.com/problems/<slug>. Baseer uw logica hierop (of op de slug), niet op title of detail
title Korte samenvatting van het type
status De HTTP-status
detail Leesbare uitleg van dit specifieke geval
errors Validatieproblemen: pointer (een JSON Pointer in de body van het request, of in de query of de variabelen), message, optioneel hint
requestId Staat ook in de header x-request-id. Vermeld het bij support
upgradeUrl Bij abonnementsbeperkingen (402, 403 plan-upgrade-required): waar u een creditcard toevoegt of upgradet

Alle validatieproblemen van een request worden tegelijk gemeld, zodat een client ze allemaal bij het juiste veld kan tonen.

Fouttypen

Section titled “Fouttypen”
Status Slug Wanneer
400 bad-request Ongeldig request, zoals een body die geen geldige JSON is
401 unauthorized Ontbrekende, ongeldig opgemaakte, ingetrokken of verlopen inloggegevens
402 payment-required Een Free-workspace heeft de inbegrepen enveloppen voor deze periode voltooid; voeg een creditcard toe of upgrade (testmodus wordt niet beïnvloed)
403 forbidden Geauthenticeerd maar niet toegestaan: een ontbrekend recht, een API-key op een endpoint dat alleen voor het dashboard is, een cross-site request
403 plan-upgrade-required De functie zit niet in het abonnement van de workspace
403 verification-required Een ondertekenaar heeft ingediend voordat de eenmalige code was geverifieerd
404 not-found De resource bestaat niet in uw organisatie, of de route bestaat niet
409 invalid-state De actie past niet bij de huidige status, bijvoorbeeld een voltooide envelop intrekken of een sessie aanmaken voor een ontvanger die al heeft ondertekend
409 not-your-turn Een ondertekenaar heeft ingediend voordat eerdere routeringsgroepen klaar waren
409 document-mismatch Het document is gewijzigd sinds het aan de ondertekenaar werd getoond (viewedDocumentHash)
409 already-signed Het e-mailadres heeft deze permanente link al ondertekend
409 in-use Een sjabloon verwijderen dat door enveloppen of ondertekeningslinks wordt gebruikt
409 no-draft Een sjabloon publiceren dat geen concept heeft
409 idempotency-in-progress Een request met dezelfde Idempotency-Key loopt nog
409 conflict Andere conflicten
410 gone Een ondertekeningssessie die al is gebruikt of is verlopen
413 payload-too-large Een upload boven de limiet (25 MB voor sjabloonbestanden)
415 unsupported-media-type Een upload van een niet-ondersteund type
422 validation-error De body, de query of de variabelen zijn ongeldig; zie errors
422 idempotency-key-reused Dezelfde Idempotency-Key is gebruikt met een ander request
422 conversion-failed Een Word-document kon niet worden geconverteerd
429 rate-limited Te veel requests; wacht het aantal seconden uit Retry-After af als die header aanwezig is
500 internal Onverwachte fout. Veilig om opnieuw te proberen met dezelfde Idempotency-Key
501 not-implemented De functionaliteit staat in het schema maar is er nog niet (bijv. sms-codes)
503 converter-unavailable, billing-unavailable Een afhankelijkheid is tijdelijk niet beschikbaar; probeer het later opnieuw

Fouten afhandelen

Section titled “Fouten afhandelen”
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})`);
  }
}