الأخطاء
تستخدم الأخطاء رموز حالة 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 (مؤشر JSON Pointer داخل جسم الطلب، أو داخل الاستعلام أو المتغيرات)، وmessage، وhint اختياريًا |
requestId |
موجود أيضًا في الترويسة x-request-id. اذكره للدعم |
upgradeUrl |
عند قيود الخطة (402، 403 plan-upgrade-required): المكان الذي تضيف فيه بطاقة أو تُرقّي خطتك |
تُبلَّغ كل مشكلات التحقق في الطلب دفعة واحدة، لكي يتمكن العميل من عرض كل منها بجوار الحقل الصحيح.
أنواع الأخطاء
Section titled “أنواع الأخطاء”| الحالة | الـ 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 |
إحدى التبعيات غير متاحة مؤقتًا؛ أعِد المحاولة لاحقًا |
معالجة الأخطاء
Section titled “معالجة الأخطاء”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})`); }}