/
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 کلید کے ساتھ ورک اسپیس کے مالک کی زبان، منسلک ایپ کے ساتھ اس شخص کی زبان جس نے اسے جوڑا۔ درست ٹوکن کے بغیر – مثلاً ٹوکن چیک سے 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 | ٹوکن کی مدت ختم یا غلط، یا کلید حذف شدہ | نیا ٹوکن لیں؛ اگر اس سے فائدہ نہ ہو تو کلید چیک کریں |
| 401 | invalid_api_key | ٹوکن کے تبادلے میں غلط کلید ID یا سیکرٹ | لاگ اِن کی معلومات چیک کریں |
| 402 | plan_limit_reached | پلان کی حد پوری ہو گئی، مثلاً مختصر لنکس کی | اپ گریڈ کریں یا اندراجات حذف کریں |
| 403 | insufficient_scope | اسکوپ موجود نہیں یا اینڈپوائنٹ API کلیدوں کے لیے فعال نہیں | درست اسکوپ کے ساتھ کلید بنائیں |
| 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 | بہت زیادہ ریکویسٹس، یا ناکام کوششوں کے بعد کلید لاک | اتنی دیر انتظار کریں جتنا 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 کی صورت میں message بتاتا ہے کہ کون سی فیلڈز نامعلوم ہیں – اکثر فیلڈ کے نام میں ٹائپنگ کی غلطی۔
آپ کے کوڈ میں تجویز کردہ طریقہ
- 400، 413 اور 422: دوبارہ کوشش نہ کریں، بلکہ ریکویسٹ ٹھیک کریں
- 401 invalid_token: ایک بار نیا ٹوکن لیں اور دوبارہ کوشش کریں
- 403: دوبارہ کوشش نہ کریں؛ اسکوپ، پلان یا یہ چیک کریں کہ یہ کام کرنے کی اجازت کسے ہے
- 404: ID چیک کریں؛ کچھ حذف کرنے کے بعد یہ معمول کی بات ہے
- 409: حالت دوبارہ لوڈ کریں اور فیصلہ کریں کہ عمل کی ابھی بھی ضرورت ہے یا نہیں
- 429: اتنی دیر انتظار کریں جتنا Retry-After بتائے، پھر دوبارہ کوشش کریں – دیکھیں ریٹ لمٹس
- 500 اور 503: بڑھتے وقفوں کے ساتھ چند بار دوبارہ کوشش کریں
یہ بھی آپ کے کام آ سکتا ہے
کچھ نہیں ملا؟
ہمیں بتائیں کہ آپ کو کیا چاہیے، ہماری سپورٹ ٹیم ذاتی طور پر آپ کی مدد کرے گی۔