ریٹ لمٹس: تمام حدیں اور ہیڈرز

API کو سب کے لیے تیز رکھنے کے لیے LinkHarbor فی منٹ ریکویسٹس کی تعداد محدود کرتا ہے۔ یہ حدیں آپ کے پلان پر منحصر نہیں – API کالز کا کوئی ماہانہ کوٹہ نہیں ہے۔ یہ مضمون ہر حد کی فہرست دیتا ہے اور دکھاتا ہے کہ آپ کا کوڈ انہیں صاف طریقے سے کیسے سنبھال سکتا ہے۔

#ریکویسٹس کیسے گنی جاتی ہیں

• ہر ریکویسٹ بالکل ایک بکٹ میں آتی ہے، مثلاً تصدیق شدہ ریکویسٹس کے لیے user یا ٹوکن کے تبادلے کے لیے token
• گنتی پورے منٹ (UTC) کے حساب سے ہوتی ہے؛ ہر نئے منٹ کے ساتھ کاؤنٹر پھر صفر سے شروع ہوتا ہے
• بکٹ کے لحاظ سے API فی ورک اسپیس، فی شخص، فی کنکشن یا فی IP پتہ گنتا ہے
• جو ریکویسٹس ٹوکن، اسکوپ یا اسکیما پر ہی ناکام ہو جائیں (401، 403 insufficient_scope، 400، اسکیما چیک سے 422 validation_failed) وہ نہیں گنی جاتیں؛ بعد کی خرابیاں جیسے 403 feature_not_available گنی جاتی ہیں

#تمام حدیں

#ہر ورک اسپیس کا ایک بجٹ

ایک ہی ورک اسپیس کی API کلیدوں کے تمام ٹوکنز فی منٹ 600 ریکویسٹس مل کر استعمال کرتے ہیں – چاہے آپ کتنی ہی کلیدیں بنائیں۔ منسلک 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 میں متن اکاؤنٹ کی زبان میں ہوتا ہے (دیکھیں API خرابی کا فارمیٹ)، یہاں انگریزی میں۔ 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; // token expired – try once more with a new token
    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;
}

// Example: const { items } = await lh('GET', '/v1/pages');

#بڑی مقدار میں ڈیٹا کے لیے مشورے

• ٹوکن کیش کریں اور اسے 15 منٹ میں مدت ختم ہونے سے کچھ پہلے ہی نیا کریں
• 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 میں فیلڈ، قاعدہ اور حد کا نام ہوتا ہے۔ کسی ریکویسٹ کا پاتھ اور کوئری اسٹرنگ مل کر زیادہ سے زیادہ 16 KB لمبے ہو سکتے ہیں۔