রেট লিমিট: সব সীমা আর হেডার

সবার জন্য API দ্রুত রাখতে LinkHarbor প্রতি মিনিটে রিকোয়েস্টের সংখ্যা সীমিত করে। সীমাগুলো আপনার প্ল্যানের ওপর নির্ভর করে না – API কলের কোনো মাসিক কোটা নেই। এই আর্টিকেলে সব সীমার তালিকা আছে, আর আপনার কোড কীভাবে সেগুলো পরিচ্ছন্নভাবে সামলাতে পারে তা দেখানো হয়েছে।

#রিকোয়েস্ট কীভাবে গোনা হয়

• প্রতিটি রিকোয়েস্ট ঠিক একটি বাকেটে পড়ে, যেমন অথেনটিকেটেড রিকোয়েস্টের জন্য user বা টোকেন বদলের জন্য token
• গণনা হয় প্রতি পূর্ণ মিনিটে (UTC); প্রতিটি নতুন মিনিটে কাউন্টার আবার শূন্য থেকে শুরু হয়
• বাকেট অনুযায়ী API গোনে প্রতি ওয়ার্কস্পেস, প্রতি ব্যক্তি, প্রতি সংযোগ বা প্রতি IP ঠিকানায়
• যেসব রিকোয়েস্ট টোকেন, স্কোপ বা স্কিমাতেই আটকে যায় (401, 403 insufficient_scope, 400, স্কিমা যাচাই থেকে 422 validation_failed), সেগুলো গোনা হয় না; পরের ধাপের ত্রুটি, যেমন 403 feature_not_available, গোনা হয়

#সব সীমা

#প্রতি ওয়ার্কস্পেসে একটি বাজেট

একই ওয়ার্কস্পেসের API কী থেকে আসা সব টোকেন মিনিটে ৬০০টি রিকোয়েস্ট ভাগাভাগি করে – আপনি যতগুলো কী-ই তৈরি করুন না কেন। সংযুক্ত AI অ্যাসিস্ট্যান্টের টুলগুলোও এখানে গোনা হয়, কারণ সেগুলো ভেতরে ভেতরে API কল করে। তাই বেশি কী সীমা বাড়ায় না। অনেক লোড কয়েকটি প্রোগ্রামে ছড়িয়ে থাকলে এই যৌথ বাজেট মাথায় রেখে পরিকল্পনা করুন।

#হেডারগুলো

X-RateLimit-Limit

বাকেটের প্রতি মিনিটের সীমা, যেমন 600।

X-RateLimit-Remaining

চলতি মিনিটে আর কতগুলো রিকোয়েস্ট বাকি আছে।

X-RateLimit-Bucket

রিকোয়েস্টটি যে বাকেটে পড়েছে, যেমন user।

Retry-After

শুধু 429 rate_limited-এ: পরের মিনিট শুরু হতে কত সেকেন্ড বাকি। api_key_locked-এ অপেক্ষার সময় থাকে details.retry_after_sec-এ।

#সীমায় পৌঁছালে

সীমায় পৌঁছালে API HTTP 429 আর এই বডি দিয়ে উত্তর দেয়। message-এর লেখা অ্যাকাউন্টের ভাষায় আসে (দেখুন ত্রুটির ফরম্যাট ও ত্রুটি কোড), এখানে ইংরেজিতে; error কোড rate_limited সবসময় একই থাকে:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Bucket: user

{ "error": "rate_limited", "message": "Too many requests. Please try again in a moment.", "retry_after_sec": 37 }

1. Retry-After বা retry_after_sec পড়ুন
2. অন্তত ততগুলো সেকেন্ড অপেক্ষা করুন, সাথে একটু এলোমেলো সময় যোগ করুন যাতে সব প্রসেস একই মুহূর্তে আবার শুরু না হয়
3. রিকোয়েস্টটি বড়জোর কয়েকবার আবার চেষ্টা করুন
4. বারবার 429 পেলে কাজটি আরও বেশি সময়ে ছড়িয়ে দিন

const BASE = 'https://dock.at-harbor.com';
let cached = null; // { token, expiresAt }

async function getToken() {
  if (cached && Date.now() < cached.expiresAt - 60_000) return cached.token;
  const res = await fetch(BASE + '/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      key_id: process.env.LH_KEY_ID,
      key_secret: process.env.LH_KEY_SECRET,
    }),
  });
  if (!res.ok) throw new Error('Token exchange failed: HTTP ' + res.status);
  const data = await res.json();
  cached = { token: data.token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

async function lh(method, path, body, attempt = 0) {
  const headers = { Authorization: 'Bearer ' + (await getToken()) };
  if (body !== undefined) headers['Content-Type'] = 'application/json';

  const res = await fetch(BASE + path, {
    method,
    headers,
    body: body === undefined ? undefined : JSON.stringify(body),
  });

  if (res.status === 429 && attempt < 3) {
    const wait = Number(res.headers.get('Retry-After') ?? 5);
    await new Promise((r) => setTimeout(r, (wait + Math.random() * 2) * 1000));
    return lh(method, path, body, attempt + 1);
  }
  if (res.status === 401 && attempt === 0) {
    cached = null; // টোকেনের মেয়াদ শেষ – নতুন টোকেন দিয়ে আরেকবার চেষ্টা
    return lh(method, path, body, attempt + 1);
  }
  const data = await res.json().catch(() => null);
  if (!res.ok) throw new Error((data && data.error) + ' (HTTP ' + res.status + ')');
  return data;
}

// উদাহরণ: const { items } = await lh('GET', '/v1/pages');

#বেশি ডেটার জন্য টিপস

• টোকেন ক্যাশ করুন এবং ১৫ মিনিটে মেয়াদ শেষ হওয়ার একটু আগে নবায়ন করুন
• X-RateLimit-Remaining খেয়াল রাখুন এবং কমে এলে গতি কমান
• ডজনখানেক সমান্তরাল সংযোগের বদলে রিকোয়েস্ট একটার পর একটা পাঠান
• প্রতিটি পেজ আলাদাভাবে জিজ্ঞাসা না করে তালিকা একবার লোড করে লোকালি ফিল্টার করুন
• বড় সিঙ্ক কয়েক মিনিটে ছড়িয়ে দিন
• 5xx ত্রুটি ক্রমশ লম্বা বিরতি দিয়ে আবার চেষ্টা করুন, কিন্তু 4xx ত্রুটি নয়

#অন্যান্য সীমা

টোকেন বদলে ব্যর্থ চেষ্টা কী আর IP সাময়িকভাবে লক করে দেয়, দেখুন API কী ও টোকেন। পুশ নোটিফিকেশন আপনি শুধু ড্যাশবোর্ডে পাঠান; এর সীমা ব্যাখ্যা করা আছে ফলোয়ার ও পুশ নোটিফিকেশন-এ।

আপনার প্ল্যানের কনটেন্ট সীমা – পেজ, লিংক, ব্লক, শর্ট লিংক ইত্যাদি – রেট লিমিট নয়, বরং নির্দিষ্ট সর্বোচ্চ সংখ্যা। এগুলোর তালিকা আছে প্ল্যানের তুলনা-এ।

#রিকোয়েস্টের আকার

API পড়ার আগেই প্রতিটি বডি মাপা হয়। এটি কত বড় হতে পারে তা এন্ডপয়েন্টের ওপর নির্ভর করে:

বডি এর চেয়ে বড় হলে API 413 request_too_large দিয়ে উত্তর দেয়; details.max_bytes আর details.max_kb সীমাটি জানায়। আপলোডে খুব বড় ফাইল হলে 413 payload_too_large আসে। বডি ছাড়া এন্ডপয়েন্ট, যেমন DELETE কলগুলো, কোনো বডি নেয় না অথবা শুধু {} নেয়।

HTTP/1.1 413 Payload Too Large

{ "error": "request_too_large", "message": "…", "details": { "max_bytes": 65536, "max_kb": 64 }, "request_id": "…" }

বডির ভেতরেও সীমা আছে: প্রতিটি টেক্সটের সর্বোচ্চ দৈর্ঘ্য আর প্রতিটি তালিকার সর্বোচ্চ এন্ট্রি সংখ্যা নির্দিষ্ট, আর অজানা ফিল্ড প্রত্যাখ্যাত হয়। মানগুলো API রেফারেন্সে প্রতিটি এন্ডপয়েন্টের জন্য দেওয়া আছে। নিয়ম ভাঙলে 422 validation_failed আসে, আর details-এ ফিল্ড, নিয়ম আর সীমার নাম থাকে। একটি রিকোয়েস্টের পাথ আর কোয়েরি স্ট্রিং মিলিয়ে সর্বোচ্চ ১৬ KB লম্বা হতে পারে।