ایررز

ایررز 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`	قسم کا مختصر خلاصہ
`status`	HTTP اسٹیٹس
`detail`	اس واقعے کی انسانی طور پر قابلِ فہم وضاحت
`errors`	ویلیڈیشن کے مسائل: `pointer` (درخواست کی باڈی، یا query یا ویری ایبلز کے اندر ایک 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 کلید، cross-site درخواست
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`	باڈی، query یا ویری ایبلز غلط ہیں؛ دیکھیں `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})`);
  }
}