এরর

এরর HTTP স্ট্যাটাস কোড এবং একটি RFC 9457 বডি ব্যবহার করে, 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"
}

সদস্য	অর্থ
`type`	স্থির আইডেন্টিফায়ার: `https://bonafidesign.com/problems/<slug>`। এটির (বা slug-এর) ওপর ভিত্তি করে ব্রাঞ্চ করুন, `title` বা `detail`-এর ওপর নয়
`title`	type-এর সংক্ষিপ্ত সারাংশ
`status`	HTTP স্ট্যাটাস
`detail`	এই ঘটনার মানুষের পড়ার উপযোগী ব্যাখ্যা
`errors`	ভ্যালিডেশনের সমস্যা: `pointer` (অনুরোধের বডিতে, অথবা কোয়েরি বা ভেরিয়েবলে একটি JSON Pointer), `message`, ঐচ্ছিক `hint`
`requestId`	`x-request-id` হেডারেও থাকে। সাপোর্টকে এটি জানান
`upgradeUrl`	প্ল্যানের সীমায় (`402`, `403 plan-upgrade-required`): কোথায় কার্ড যোগ করবেন বা আপগ্রেড করবেন

একটি অনুরোধের সব ভ্যালিডেশন সমস্যা একসঙ্গে জানানো হয়, যাতে ক্লায়েন্ট প্রতিটি সমস্যা সঠিক ফিল্ডের পাশে দেখাতে পারে।

এররের ধরন

স্ট্যাটাস	Slug	কখন
400	`bad-request`	ভুল গঠনের অনুরোধ, যেমন এমন বডি যা বৈধ JSON নয়
401	`unauthorized`	অনুপস্থিত, ভুল ফরম্যাটের, প্রত্যাহার করা বা মেয়াদোত্তীর্ণ ক্রেডেনশিয়াল
402	`payment-required`	একটি Free ওয়ার্কস্পেস এই সময়কালের অন্তর্ভুক্ত খামগুলো সম্পন্ন করে ফেলেছে; কার্ড যোগ করুন বা আপগ্রেড করুন (টেস্ট মোডে প্রভাব পড়ে না)
403	`forbidden`	অথেন্টিকেটেড, কিন্তু অনুমোদিত নয়: অনুপস্থিত অনুমতি, শুধু-ড্যাশবোর্ড এন্ডপয়েন্টে API কী, ক্রস-সাইট অনুরোধ
403	`plan-upgrade-required`	ফিচারটি ওয়ার্কস্পেসের প্ল্যানে নেই
403	`verification-required`	একজন স্বাক্ষরকারী তাঁর এককালীন কোড যাচাইয়ের আগে জমা দিয়েছেন
404	`not-found`	রিসোর্সটি আপনার সংস্থায় নেই, অথবা রুটটির অস্তিত্ব নেই
409	`invalid-state`	কাজটি বর্তমান অবস্থার সঙ্গে খাপ খায় না, যেমন একটি সম্পন্ন খাম বাতিল করা বা ইতিমধ্যে স্বাক্ষর করা প্রাপকের জন্য সেশন তৈরি করা
409	`not-your-turn`	আগের রাউটিং দলগুলো শেষ হওয়ার আগে একজন স্বাক্ষরকারী জমা দিয়েছেন
409	`document-mismatch`	স্বাক্ষরকারীকে দেখানোর পর থেকে নথিটি বদলে গেছে (`viewedDocumentHash`)
409	`already-signed`	ইমেইল ঠিকানাটি এই সবসময় চালু লিংকে আগেই স্বাক্ষর করেছে
409	`in-use`	এমন টেমপ্লেট মুছে ফেলা, যা খাম বা স্বাক্ষর লিংক ব্যবহার করে
409	`no-draft`	এমন টেমপ্লেট প্রকাশ করা, যার কোনো খসড়া নেই
409	`idempotency-in-progress`	একই `Idempotency-Key`-যুক্ত একটি অনুরোধ এখনো চলছে
409	`conflict`	অন্যান্য দ্বন্দ্ব
410	`gone`	এমন একটি স্বাক্ষর সেশন, যা আগেই ব্যবহৃত হয়েছে বা যার মেয়াদ শেষ
413	`payload-too-large`	সীমার চেয়ে বড় আপলোড (টেমপ্লেট ফাইলের জন্য 25 MB)
415	`unsupported-media-type`	অসমর্থিত ধরনের আপলোড
422	`validation-error`	বডি, কোয়েরি বা ভেরিয়েবল অবৈধ; `errors` দেখুন
422	`idempotency-key-reused`	একই `Idempotency-Key` ভিন্ন একটি অনুরোধের সঙ্গে ব্যবহার করা হয়েছে
422	`conversion-failed`	একটি Word নথি রূপান্তর করা যায়নি
429	`rate-limited`	অনেক বেশি অনুরোধ; `Retry-After` থাকলে তত সেকেন্ড অপেক্ষা করুন
500	`internal`	অপ্রত্যাশিত এরর। একই `Idempotency-Key` দিয়ে রিট্রাই করা নিরাপদ
501	`not-implemented`	ক্ষমতাটি স্কিমায় আছে, কিন্তু এখনো চালু হয়নি (যেমন SMS কোড)
503	`converter-unavailable`, `billing-unavailable`	একটি নির্ভরতা সাময়িকভাবে অনুপলব্ধ; পরে রিট্রাই করুন

এরর সামলানো

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