דלגו לתוכן
bona fidedocs

שגיאות

שגיאות משתמשות בקודי סטטוס של 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})`);
  }
}