Hatalar

Hatalar HTTP durum kodlarını ve Content-Type: application/problem+json ile bir RFC 9457 gövdesini kullanır:

{
  "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"
}

Üye	Anlamı
`type`	Sabit tanımlayıcı: `https://bonafidesign.com/problems/<slug>`. Dallanmayı `title` veya `detail` üzerinden değil, bunun (veya slug’ın) üzerinden yapın
`title`	Türün kısa özeti
`status`	HTTP durumu
`detail`	Bu oluşumun insan tarafından okunabilir açıklaması
`errors`	Doğrulama sorunları: `pointer` (istek gövdesine veya sorguya ya da değişkenlere işaret eden bir JSON Pointer), `message`, isteğe bağlı `hint`
`requestId`	`x-request-id` başlığında da bulunur. Destekle iletişimde belirtin
`upgradeUrl`	Plan engellerinde (`402`, `403 plan-upgrade-required`): kart eklenecek veya plan yükseltilecek yer

Bir isteğin tüm doğrulama sorunları tek seferde bildirilir; böylece bir istemci her birini ilgili alanın yanında gösterebilir.

Hata türleri

Durum	Slug	Ne zaman
400	`bad-request`	Geçerli JSON olmayan bir gövde gibi hatalı biçimlendirilmiş istek
401	`unauthorized`	Eksik, hatalı biçimlendirilmiş, iptal edilmiş veya süresi dolmuş kimlik bilgileri
402	`payment-required`	Bir Free çalışma alanı bu dönemdeki dahil zarflarını tamamladı; kart ekleyin veya planı yükseltin (test modu etkilenmez)
403	`forbidden`	Kimlik doğrulandı ancak izin yok: eksik bir izin, yalnızca panele açık bir uç noktada API anahtarı, siteler arası bir istek
403	`plan-upgrade-required`	Özellik çalışma alanının planında yok
403	`verification-required`	Bir imzacı tek kullanımlık kodunu doğrulamadan gönderim yaptı
404	`not-found`	Kaynak kuruluşunuzda mevcut değil veya yol mevcut değil
409	`invalid-state`	Eylem mevcut duruma uymuyor; örneğin tamamlanmış bir zarfı iptal etmek veya imzalamış bir alıcı için oturum oluşturmak
409	`not-your-turn`	Bir imzacı, önceki yönlendirme grupları bitmeden gönderim yaptı
409	`document-mismatch`	Belge, imzacıya gösterildikten sonra değişti (`viewedDocumentHash`)
409	`already-signed`	E-posta adresi bu kalıcı bağlantıyı zaten imzaladı
409	`in-use`	Zarfların veya imzalama bağlantılarının kullandığı bir şablonu silme
409	`no-draft`	Taslağı olmayan bir şablonu yayımlama
409	`idempotency-in-progress`	Aynı `Idempotency-Key` değerine sahip bir istek hâlâ çalışıyor
409	`conflict`	Diğer çakışmalar
410	`gone`	Zaten kullanılmış veya süresi dolmuş bir imzalama oturumu
413	`payload-too-large`	Sınırını aşan bir yükleme (şablon dosyaları için 25 MB)
415	`unsupported-media-type`	Desteklenmeyen türde bir yükleme
422	`validation-error`	Gövde, sorgu veya değişkenler geçersiz; bkz. `errors`
422	`idempotency-key-reused`	Aynı `Idempotency-Key` farklı bir istekle kullanıldı
422	`conversion-failed`	Bir Word belgesi dönüştürülemedi
429	`rate-limited`	Çok fazla istek; varsa `Retry-After` saniye kadar bekleyin
500	`internal`	Beklenmeyen hata. Aynı `Idempotency-Key` ile yeniden denemek güvenlidir
501	`not-implemented`	Yetenek şemada var ancak henüz uygulanmadı (örn. SMS kodları)
503	`converter-unavailable`, `billing-unavailable`	Bir bağımlılık geçici olarak kullanılamıyor; daha sonra yeniden deneyin

Hataları işleme

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