Errori

Gli errori usano i codici di stato HTTP e un corpo conforme a RFC 9457 con 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"
}

Membro	Significato
`type`	Identificatore stabile: `https://bonafidesign.com/problems/<slug>`. Basi la logica su questo (o sullo slug), non su `title` o `detail`
`title`	Breve riepilogo del tipo
`status`	Lo stato HTTP
`detail`	Spiegazione leggibile di questa specifica occorrenza
`errors`	Problemi di validazione: `pointer` (un JSON Pointer nel corpo della richiesta, oppure nella query o nelle variabili), `message`, `hint` facoltativo
`requestId`	Presente anche nell’header `x-request-id`. Lo indichi all’assistenza
`upgradeUrl`	Nei blocchi legati al piano (`402`, `403 plan-upgrade-required`): dove aggiungere una carta o eseguire l’upgrade

Tutti i problemi di validazione di una richiesta vengono segnalati insieme, così un client può mostrarli tutti accanto al campo corretto.

Tipi di errore

Stato	Slug	Quando
400	`bad-request`	Richiesta malformata, ad esempio un corpo che non è JSON valido
401	`unauthorized`	Credenziali mancanti, malformate, revocate o scadute
402	`payment-required`	Un workspace Free ha completato le buste incluse in questo periodo; aggiunga una carta o esegua l’upgrade (la modalità di prova non è interessata)
403	`forbidden`	Autenticato ma non autorizzato: un’autorizzazione mancante, una chiave API su un endpoint riservato alla dashboard, una richiesta cross-site
403	`plan-upgrade-required`	La funzionalità non è inclusa nel piano del workspace
403	`verification-required`	Un firmatario ha inviato prima di verificare il proprio codice monouso
404	`not-found`	La risorsa non esiste nella Sua organizzazione, oppure il percorso non esiste
409	`invalid-state`	L’azione non è compatibile con lo stato attuale, ad esempio l’annullamento di una busta completata o la creazione di una sessione per un destinatario che ha già firmato
409	`not-your-turn`	Un firmatario ha inviato prima che i gruppi di instradamento precedenti avessero terminato
409	`document-mismatch`	Il documento è cambiato da quando è stato mostrato al firmatario (`viewedDocumentHash`)
409	`already-signed`	L’indirizzo e-mail ha già firmato questo link sempre attivo
409	`in-use`	Eliminazione di un modello usato da buste o link di firma
409	`no-draft`	Pubblicazione di un modello che non ha una bozza
409	`idempotency-in-progress`	Una richiesta con la stessa `Idempotency-Key` è ancora in esecuzione
409	`conflict`	Altri conflitti
410	`gone`	Una sessione di firma già usata o scaduta
413	`payload-too-large`	Un caricamento oltre il limite (25 MB per i file dei modelli)
415	`unsupported-media-type`	Un caricamento di un tipo non supportato
422	`validation-error`	Il corpo, la query o le variabili non sono validi; veda `errors`
422	`idempotency-key-reused`	La stessa `Idempotency-Key` è stata usata con una richiesta diversa
422	`conversion-failed`	Non è stato possibile convertire un documento Word
429	`rate-limited`	Troppe richieste; attenda i secondi indicati da `Retry-After`, se presente
500	`internal`	Errore imprevisto. Si può ritentare in sicurezza con la stessa `Idempotency-Key`
501	`not-implemented`	La funzionalità esiste nello schema ma non è ancora disponibile (ad esempio i codici SMS)
503	`converter-unavailable`, `billing-unavailable`	Una dipendenza è temporaneamente non disponibile; riprovi più tardi

Gestione degli errori

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