/
LinkHarbor API के त्रुटि जवाब कैसे बने होते हैं, सबसे ज़रूरी त्रुटि कोड का क्या मतलब है और आपका कोड उन पर कैसे प्रतिक्रिया दे।
API का हर त्रुटि जवाब एक ही फ़ॉर्मैट में होता है। आपके कोड को error फ़ील्ड के त्रुटि कोड पर निर्भर रहना चाहिए, message के टेक्स्ट पर नहीं – कोड स्थिर रहता है, जबकि टेक्स्ट बदल सकता है और अकाउंट की भाषा में अनुवादित होता है।
त्रुटि जवाब की संरचना
{
"error": "validation_failed",
"message": "Some of the information provided is invalid. Please check and try again.",
"details": [
{ "field": "title", "reason": "minLength", "message": "…" }
],
"request_id": "6b1f0c2e-…"
}- error
- मशीन से पढ़ा जा सकने वाला कोड, जैसे not_found। ज़्यादातर त्रुटियों में यह X-Error-Code हेडर में भी होता है – लेकिन बॉडी के फ़ील्ड पर निर्भर रहें।
- message
- इंसानों के पढ़ने लायक विवरण, अकाउंट की भाषा में: API key के साथ वर्कस्पेस के मालिक की भाषा, कनेक्ट किए गए ऐप के साथ उस व्यक्ति की भाषा जिसने उसे कनेक्ट किया। वैध टोकन के बिना – जैसे टोकन जाँच से आए 401 में – भाषा Accept-Language के हिसाब से होती है, वरना अंग्रेज़ी। Content-Language हेडर बताता है कि कौन-सी भाषा इस्तेमाल हुई।
- details
- सिर्फ़ तब होता है जब बताने को कुछ और हो। इनपुट जाँच से आए 422 के लिए हर समस्या के लिए field, reason और message वाली एक सूची; बिज़नेस लॉजिक से आए 422 और बाकी सभी त्रुटियों के लिए एक ऑब्जेक्ट, जैसे reason, retry_after_sec या issues की सूची के साथ। कोई साइज़ पार होने पर इसमें field, reason और limit होते हैं, और 413 request_too_large के लिए max_bytes और max_kb। इसलिए जाँचें कि details एक सूची है या नहीं।
- request_id
- अनुरोध की ID। यह X-Request-Id हेडर में भी होती है। सपोर्ट से संपर्क करते समय इसे शामिल करें।
अपवाद: 429 rate_limited जवाब में details की जगह retry_after_sec फ़ील्ड होता है; 429 और 403 insufficient_scope में बॉडी में request_id नहीं होता। टोकन जाँच से आए 401 और स्कीमा जाँच से आए 422 में X-Error-Code हेडर नहीं होता, और स्कीमा जाँच में सिर्फ़ सबसे ऊपर वाले message का अनुवाद होता है, details के अंदर के टेक्स्ट अंग्रेज़ी में रहते हैं। X-Request-Id हेडर हमेशा सेट होता है।
सबसे ज़रूरी कोड
| HTTP | error | मतलब | क्या करें |
|---|---|---|---|
| 400 | invalid_json | बॉडी वैध JSON नहीं है | JSON जाँचें |
| 400 | bad_request | ग़लत Content-Type या बिगड़ा हुआ अनुरोध | Content-Type: application/json सेट करें |
| 401 | missing_bearer_token | Authorization हेडर में कोई टोकन नहीं | Authorization: Bearer … हेडर सेट करें |
| 401 | invalid_token | टोकन की अवधि ख़त्म या अमान्य, या key हटाई गई | नया टोकन लें; इससे मदद न मिले तो key जाँचें |
| 401 | invalid_api_key | टोकन बदलते समय ग़लत key ID या secret | लॉगिन जानकारी जाँचें |
| 402 | plan_limit_reached | प्लान की सीमा पूरी, जैसे शॉर्ट लिंक के लिए | अपग्रेड करें या एंट्री हटाएँ |
| 403 | insufficient_scope | स्कोप नहीं है या एंडपॉइंट API keys के लिए चालू नहीं है | सही स्कोप वाली key बनाएँ |
| 403 | forbidden | इस काम की अनुमति नहीं | इसे डैशबोर्ड में करें |
| 403 | feature_not_available | फ़ीचर प्लान में शामिल नहीं | प्लान जाँचें |
| 403 | block_type_requires_plan | ब्लॉक प्रकार सिर्फ़ ऊँचे प्लान में उपलब्ध | दूसरा ब्लॉक प्रकार चुनें या अपग्रेड करें |
| 403 | template_locked | प्रीमियम टेम्पलेट मौजूदा प्लान में उपलब्ध नहीं | GET /v1/templates/available से कोई टेम्पलेट चुनें |
| 403 | workspace_suspended, workspace_read_only, workspace_grace_expired | बाकी भुगतान के कारण वर्कस्पेस लॉक या सिर्फ़ पढ़ने लायक | डैशबोर्ड में भुगतान ठीक करें |
| 404 | not_found | रिसोर्स मौजूद नहीं है या आपके वर्कस्पेस का नहीं है | ID जाँचें |
| 409 | conflict | मौजूदा स्थिति से सामान्य टकराव | स्थिति फिर से लोड करें, इनपुट बदलें |
| 409 | workspace_template_in_use | वर्कस्पेस टेम्पलेट अभी भी पेजों में इस्तेमाल हो रहा है; संख्या details.count में है | पेजों को दूसरे टेम्पलेट पर ले जाएँ, फिर उसे हटाएँ |
| 409 | handle_taken, slug_taken | हैंडल या शॉर्ट लिंक स्लग पहले से लिया जा चुका है | कोई दूसरी वैल्यू चुनें |
| 409 | form_in_use, page_not_private, page_not_published, never_published | स्थिति से टकराव: फ़ॉर्म अभी किसी पेज पर है, पेज निजी या पब्लिश नहीं है, कभी पब्लिश नहीं हुआ | स्थिति बदलें, फिर दोबारा कोशिश करें |
| 409 | page_limit_reached, link_limit_reached, block_limit_reached, form_limit_reached, asset_limit_reached, asset_storage_limit_reached, workspace_template_limit_reached | प्लान की संख्या या स्टोरेज सीमा पूरी | एंट्री हटाएँ या अपग्रेड करें |
| 409 | draft_not_publishable | ड्राफ़्ट में समस्याएँ हैं; सूची details.issues में है | समस्याएँ ठीक करें, फिर दोबारा पब्लिश करें |
| 413 | request_too_large | इस एंडपॉइंट की अनुमति से बड़ी बॉडी (64 KB, 1 MB या 2 MB); सीमा details.max_kb में है | हर अनुरोध में कम डेटा भेजें, देखें रेट लिमिट |
| 413 | payload_too_large | अपलोड की गई फ़ाइल 10 MB से बड़ी | फ़ाइल छोटी करें |
| 422 | validation_failed | अमान्य इनपुट या अज्ञात फ़ील्ड; विवरण details में | details में बताए अनुसार फ़ील्ड ठीक करें |
| 422 | handle_reserved, target_url_invalid, target_url_scheme, target_url_host | हैंडल आरक्षित है, या लक्ष्य URL अमान्य या अनुमत नहीं | कोई दूसरी वैल्यू चुनें |
| 422 | workspace_template_disabled | चुना गया वर्कस्पेस टेम्पलेट बंद है | “डोमेन और टेम्पलेट” के तहत टेम्पलेट चालू करें या कोई दूसरा चुनें |
| 422 | template_css_external, template_section_invalid | वर्कस्पेस टेम्पलेट: CSS बाहरी सर्वर से लोड करता है, या कोई {{#if}}/{{#unless}}/{{#each}} सेक्शन ग़लत जगह है | बाहरी पते हटाएँ, या सेक्शन को उसी टैग या टेक्स्ट में बंद करें |
| 422 | custom_css_external | कस्टम CSS बाहरी सर्वर से कुछ लोड करता है | CSS से बाहरी पते हटाएँ |
| 429 | rate_limited, api_key_locked | बहुत ज़्यादा अनुरोध, या असफल कोशिशों के बाद key लॉक | उतना इंतज़ार करें जितना Retry-After या details.retry_after_sec बताता है |
| 500 | internal_error | अनपेक्षित त्रुटि | बाद में फिर कोशिश करें, request_id नोट करें |
| 503 | service_unavailable | सेवा अस्थायी रूप से उपलब्ध नहीं | थोड़ा रुककर फिर कोशिश करें |
इनपुट त्रुटियाँ पढ़ना
422 validation_failed के साथ details हर समस्या अलग-अलग बताता है: field फ़ील्ड का पाथ है (नेस्ट किए गए ऑब्जेक्ट के लिए स्लैश के साथ, जैसे theme_config/button_style), reason वह नियम है जो टूटा, जैसे required, minLength, maxLength, enum या additionalProperties। additionalProperties के साथ संदेश बताता है कि कौन-से फ़ील्ड अज्ञात हैं – अक्सर फ़ील्ड के नाम में टाइपो।
आपके कोड में सुझाया गया तरीका
- 400, 413 और 422: दोहराएँ नहीं, बल्कि अनुरोध ठीक करें
- 401 invalid_token: एक बार नया टोकन लें और दोहराएँ
- 403: दोहराएँ नहीं; स्कोप, प्लान या यह जाँचें कि यह काम करने की अनुमति किसे है
- 404: ID जाँचें; किसी चीज़ को हटाने के बाद यह सामान्य है
- 409: स्थिति फिर से लोड करें और तय करें कि काम अब भी ज़रूरी है या नहीं
- 429: उतना इंतज़ार करें जितना Retry-After बताता है, फिर दोहराएँ – देखें रेट लिमिट
- 500 और 503: बढ़ते अंतराल के साथ कुछ बार दोहराएँ
यह भी आपके काम आ सकता है
कुछ नहीं मिला?
हमें बताएँ कि आपको क्या चाहिए, और हमारी सपोर्ट टीम ख़ुद आपकी मदद करेगी।