एरर

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