Virheet

Virheet käyttävät HTTP-tilakoodeja ja RFC 9457 -muotoista runkoa, jonka 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"
}

Jäsen	Merkitys
`type`	Pysyvä tunniste: `https://bonafidesign.com/problems/<slug>`. Haaraudu tämän (tai slugin) perusteella, älä kenttien `title` tai `detail`
`title`	Lyhyt yhteenveto tyypistä
`status`	HTTP-tila
`detail`	Ihmisluettava selitys juuri tästä tapauksesta
`errors`	Validointiongelmat: `pointer` (JSON Pointer pyynnön runkoon tai kyselyyn tai muuttujiin), `message`, valinnainen `hint`
`requestId`	Myös otsakkeessa `x-request-id`. Mainitse se tuelle
`upgradeUrl`	Pakettirajoissa (`402`, `403 plan-upgrade-required`): missä lisätä kortti tai päivittää paketti

Kaikki pyynnön validointiongelmat raportoidaan kerralla, joten asiakasohjelma voi näyttää jokaisen niistä oikean kentän vieressä.

Virhetyypit

Tila	Slug	Milloin
400	`bad-request`	Virheellinen pyyntö, esimerkiksi runko, joka ei ole kelvollista JSONia
401	`unauthorized`	Puuttuvat, virheellisen muotoiset, peruutetut tai vanhentuneet tunnistetiedot
402	`payment-required`	Free-työtila on viimeistellyt tämän jakson sisältyvät kirjekuorensa; lisää kortti tai päivitä paketti (ei vaikuta testitilaan)
403	`forbidden`	Todennettu mutta ei sallittu: puuttuva käyttöoikeus, API-avain päätepisteessä, joka hyväksyy vain hallintapaneelin, sivustojen välinen pyyntö
403	`plan-upgrade-required`	Ominaisuus ei sisälly työtilan pakettiin
403	`verification-required`	Allekirjoittaja lähetti ennen kertakäyttökoodinsa vahvistamista
404	`not-found`	Resurssia ei ole organisaatiossasi, tai reittiä ei ole olemassa
409	`invalid-state`	Toiminto ei sovi nykyiseen tilaan, esim. valmiin kirjekuoren mitätöinti tai istunnon luominen jo allekirjoittaneelle vastaanottajalle
409	`not-your-turn`	Allekirjoittaja lähetti ennen kuin aiemmat reititysryhmät olivat valmiita
409	`document-mismatch`	Asiakirja on muuttunut sen jälkeen, kun se näytettiin allekirjoittajalle (`viewedDocumentHash`)
409	`already-signed`	Sähköpostiosoite on jo allekirjoittanut tämän pysyvän linkin
409	`in-use`	Sellaisen mallin poistaminen, jota kirjekuoret tai allekirjoituslinkit käyttävät
409	`no-draft`	Sellaisen mallin julkaiseminen, jolla ei ole luonnosta
409	`idempotency-in-progress`	Pyyntö samalla `Idempotency-Key`-arvolla on yhä käynnissä
409	`conflict`	Muut ristiriidat
410	`gone`	Allekirjoitusistunto, joka on jo käytetty tai vanhentunut
413	`payload-too-large`	Latauksen koko ylittää rajan (malleille 25 Mt)
415	`unsupported-media-type`	Ladatun tiedoston tyyppiä ei tueta
422	`validation-error`	Runko, kysely tai muuttujat ovat virheellisiä; katso `errors`
422	`idempotency-key-reused`	Samaa `Idempotency-Key`-arvoa käytettiin eri pyynnössä
422	`conversion-failed`	Word-asiakirjaa ei voitu muuntaa
429	`rate-limited`	Liian monta pyyntöä; odota `Retry-After` sekuntia, kun se on annettu
500	`internal`	Odottamaton virhe. Turvallista yrittää uudelleen samalla `Idempotency-Key`-arvolla
501	`not-implemented`	Ominaisuus on skeemassa mutta ei vielä käytössä (esim. SMS-koodit)
503	`converter-unavailable`, `billing-unavailable`	Riippuvuus on tilapäisesti poissa käytöstä; yritä myöhemmin uudelleen

Virheiden käsittely

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