Fehler

Fehler verwenden HTTP-Statuscodes und einen Body nach RFC 9457 mit 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"
}

Member	Bedeutung
`type`	Stabiler Bezeichner: `https://bonafidesign.com/problems/<slug>`. Verzweigen Sie anhand dieses Werts (oder des Slugs), nicht anhand von `title` oder `detail`
`title`	Kurze Zusammenfassung des Typs
`status`	Der HTTP-Status
`detail`	Für Menschen lesbare Erklärung dieses konkreten Vorkommens
`errors`	Validierungsprobleme: `pointer` (ein JSON Pointer in den Request-Body oder in Query oder Variablen), `message`, optional `hint`
`requestId`	Auch im Header `x-request-id`. Geben Sie sie beim Support an
`upgradeUrl`	Bei Tarifgrenzen (`402`, `403 plan-upgrade-required`): wo Sie eine Karte hinterlegen oder upgraden

Alle Validierungsprobleme einer Anfrage werden auf einmal gemeldet, sodass ein Client jedes davon neben dem richtigen Feld anzeigen kann.

Fehlertypen

Status	Slug	Wann
400	`bad-request`	Fehlerhafte Anfrage, etwa ein Body, der kein gültiges JSON ist
401	`unauthorized`	Fehlende, fehlerhafte, widerrufene oder abgelaufene Zugangsdaten
402	`payment-required`	Ein Free-Workspace hat in diesem Zeitraum seine enthaltenen Umschläge abgeschlossen; hinterlegen Sie eine Karte oder upgraden Sie (der Testmodus ist nicht betroffen)
403	`forbidden`	Authentifiziert, aber nicht erlaubt: eine fehlende Berechtigung, ein API-Schlüssel an einem Endpunkt nur für das Dashboard, eine Cross-Site-Anfrage
403	`plan-upgrade-required`	Die Funktion ist im Tarif des Workspace nicht enthalten
403	`verification-required`	Ein Unterzeichner hat abgesendet, bevor er seinen Einmalcode bestätigt hat
404	`not-found`	Die Ressource existiert in Ihrer Organisation nicht, oder die Route existiert nicht
409	`invalid-state`	Die Aktion passt nicht zum aktuellen Zustand, z. B. das Stornieren eines abgeschlossenen Umschlags oder das Erzeugen einer Sitzung für einen Empfänger, der bereits unterschrieben hat
409	`not-your-turn`	Ein Unterzeichner hat abgesendet, bevor frühere Routing-Gruppen fertig waren
409	`document-mismatch`	Das Dokument hat sich geändert, seit es dem Unterzeichner angezeigt wurde (`viewedDocumentHash`)
409	`already-signed`	Die E-Mail-Adresse hat diesen dauerhaften Link bereits unterschrieben
409	`in-use`	Löschen einer Vorlage, die von Umschlägen oder Signaturlinks verwendet wird
409	`no-draft`	Veröffentlichen einer Vorlage ohne Entwurf
409	`idempotency-in-progress`	Eine Anfrage mit demselben `Idempotency-Key` läuft noch
409	`conflict`	Sonstige Konflikte
410	`gone`	Eine Signatursitzung, die bereits verwendet wurde oder abgelaufen ist
413	`payload-too-large`	Ein Upload über seinem Limit (25 MB für Vorlagendateien)
415	`unsupported-media-type`	Ein Upload eines nicht unterstützten Typs
422	`validation-error`	Body, Query oder Variablen sind ungültig; siehe `errors`
422	`idempotency-key-reused`	Derselbe `Idempotency-Key` wurde mit einer anderen Anfrage verwendet
422	`conversion-failed`	Ein Word-Dokument konnte nicht umgewandelt werden
429	`rate-limited`	Zu viele Anfragen; warten Sie `Retry-After` Sekunden, wenn der Header vorhanden ist
500	`internal`	Unerwarteter Fehler. Kann mit demselben `Idempotency-Key` gefahrlos wiederholt werden
501	`not-implemented`	Die Funktion steht im Schema, ist aber noch nicht umgesetzt (z. B. SMS-Codes)
503	`converter-unavailable`, `billing-unavailable`	Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut

Fehler behandeln

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