Błędy

Błędy korzystają z kodów statusu HTTP i treści w formacie RFC 9457 z nagłówkiem 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"
}

Element	Znaczenie
`type`	Stały identyfikator: `https://bonafidesign.com/problems/<slug>`. Rozgałęziaj logikę na jego podstawie (lub na podstawie slugu), a nie na podstawie `title` czy `detail`
`title`	Krótkie podsumowanie typu
`status`	Status HTTP
`detail`	Czytelne dla człowieka wyjaśnienie tego wystąpienia
`errors`	Problemy walidacji: `pointer` (JSON Pointer wskazujący miejsce w treści żądania albo w parametrach zapytania lub zmiennych), `message`, opcjonalnie `hint`
`requestId`	Występuje też w nagłówku `x-request-id`. Podawaj go pomocy technicznej
`upgradeUrl`	Przy ograniczeniach planu (`402`, `403 plan-upgrade-required`): gdzie dodać kartę lub zmienić plan na wyższy

Wszystkie problemy walidacji żądania są zgłaszane naraz, więc klient może pokazać każdy z nich przy właściwym polu.

Typy błędów

Status	Slug	Kiedy
400	`bad-request`	Nieprawidłowo sformułowane żądanie, np. treść, która nie jest poprawnym JSON
401	`unauthorized`	Brakujące, nieprawidłowe, odwołane lub wygasłe poświadczenia
402	`payment-required`	Przestrzeń robocza w planie Free zakończyła w tym okresie zawarte w planie koperty; dodaj kartę lub zmień plan na wyższy (nie dotyczy trybu testowego)
403	`forbidden`	Uwierzytelniono, ale brak zgody: brakujące uprawnienie, klucz API użyty w punkcie końcowym dostępnym tylko dla panelu, żądanie z innej witryny
403	`plan-upgrade-required`	Funkcja nie jest dostępna w planie przestrzeni roboczej
403	`verification-required`	Osoba podpisująca przesłała podpis przed weryfikacją jednorazowego kodu
404	`not-found`	Zasób nie istnieje w Twojej organizacji lub trasa nie istnieje
409	`invalid-state`	Działanie nie pasuje do bieżącego stanu, np. unieważnienie zakończonej koperty lub utworzenie sesji dla odbiorcy, który już podpisał
409	`not-your-turn`	Osoba podpisująca przesłała podpis, zanim zakończyły się wcześniejsze grupy kierowania
409	`document-mismatch`	Dokument zmienił się od chwili, gdy został wyświetlony osobie podpisującej (`viewedDocumentHash`)
409	`already-signed`	Ten adres e-mail już podpisał przez ten stały link
409	`in-use`	Usuwanie szablonu, którego używają koperty lub linki do podpisu
409	`no-draft`	Publikowanie szablonu, który nie ma wersji roboczej
409	`idempotency-in-progress`	Żądanie z tym samym `Idempotency-Key` jest nadal przetwarzane
409	`conflict`	Inne konflikty
410	`gone`	Sesja podpisywania, która została już użyta lub wygasła
413	`payload-too-large`	Przesyłany plik przekracza limit (25 MB dla plików szablonów)
415	`unsupported-media-type`	Przesyłany plik ma nieobsługiwany typ
422	`validation-error`	Treść, parametry zapytania lub zmienne są nieprawidłowe; zobacz `errors`
422	`idempotency-key-reused`	Ten sam `Idempotency-Key` użyto z innym żądaniem
422	`conversion-failed`	Nie udało się skonwertować dokumentu Word
429	`rate-limited`	Zbyt wiele żądań; jeśli jest nagłówek `Retry-After`, odczekaj podaną w nim liczbę sekund
500	`internal`	Nieoczekiwany błąd. Można bezpiecznie ponowić z tym samym `Idempotency-Key`
501	`not-implemented`	Funkcja istnieje w schemacie, ale nie jest jeszcze dostępna (np. kody SMS)
503	`converter-unavailable`, `billing-unavailable`	Zależność jest chwilowo niedostępna; spróbuj ponownie później

Obsługa błędów

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