/
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 বা সমস্যার একটি তালিকাসহ। কোনো আকার ছাড়িয়ে গেলে এতে field, reason আর limit থাকে, আর 413 request_too_large-এ max_bytes আর max_kb। তাই details একটি তালিকা কি না তা যাচাই করুন।
- request_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 | টোকেন বদলের সময় ভুল কী আইডি বা সিক্রেট | ক্রেডেনশিয়াল যাচাই করুন |
| 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 | রিসোর্সটি নেই বা আপনার ওয়ার্কস্পেসের নয় | আইডি যাচাই করুন |
| 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 | বডি এই এন্ডপয়েন্টের অনুমোদিত আকারের চেয়ে বড় (৬৪ KB, ১ MB বা ২ MB); সীমাটি details.max_kb-এ | প্রতি রিকোয়েস্টে কম ডেটা পাঠান, দেখুন রেট লিমিট |
| 413 | payload_too_large | আপলোড করা ফাইল ১০ 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: আইডি যাচাই করুন; কিছু মোছার পর এটি স্বাভাবিক
- 409: অবস্থা আবার লোড করুন এবং কাজটি এখনো দরকার কি না ঠিক করুন
- 429: Retry-After যতক্ষণ বলে ততক্ষণ অপেক্ষা করুন, তারপর আবার চেষ্টা করুন – দেখুন রেট লিমিট
- 500 আর 503: ক্রমশ লম্বা বিরতি দিয়ে কয়েকবার আবার চেষ্টা করুন
এগুলোও কাজে আসতে পারে
কিছু খুঁজে পাননি?
আপনার কী দরকার তা আমাদের জানান, আমাদের সাপোর্ট টিম ব্যক্তিগতভাবে আপনাকে সাহায্য করবে।