راهنما
سقف درخواست، سهمیه روزانه و هدرها
هر پلن سقف درخواست در دقیقه و سهمیه روزانه دارد. با هدرهای پاسخ وضعیت را بخوانید و با کش و ارسال زنده کمتر مصرف کنید.
دو سقف مستقل
| سقف | شمارش | پس از پر شدن |
|---|---|---|
| درخواست در دقیقه | پنجره یکدقیقهای برای هر کلید | ۴۲۹ rate_limited با Retry-After: 60 |
| سهمیه روزانه | از نیمهشب تا نیمهشب به وقت تهران، برای هر کلید | ۴۲۹ daily_quota_exceeded تا روز بعد |
| اتصال زنده همزمان | حداکثر ۵ اتصال /v1/stream برای هر کلید | ۴۲۹ too_many_streams |
درخواستهایی که بهخاطر سقف رد میشوند از سهمیه کم نمیشوند و در داشبورد جداگانه (رد شده) نشان داده میشوند.
توسعه روی localhost رایگان است
درخواستی که از صفحهای روی localhost، *.localhost یا 127.0.0.1 فرستاده شود (مرورگر خودش هدرOrigin یا Referer را میفرستد) تا سقف روزانه توسعه، اکنون ۱۰۰۰ درخواست برای هر کلید، رایگان است: از سهمیه روزانه پلن کم نمیشود و محدودیت «دامنههای مجاز» کلید هم برایش اعمال نمیشود؛ پس میتوانید ویجت و کد سمت مرورگر را پیش از انتشار روی سیستم خودتان آزمایش کنید. هدر X-Local-Free-Remaining باقیمانده امروز را نشان میدهد.
- کلید معتبر و پلن فعال لازم است؛ پلن «دمو» رایگان برای شروع کافی است.
- سقف درخواست در دقیقه پلن همچنان اعمال میشود.
- بعد از سقف رایگان، درخواستها مثل همیشه از سهمیه پلن کم میشوند.
- «IPهای مجاز» کلید (برای کلید سمت سرور) همچنان بررسی میشود.
هدرهای پاسخ
| هدر | معنی |
|---|---|
X-RateLimit-Limit | سقف درخواست در دقیقه پلن شما |
X-Quota-Limit | سهمیه روزانه (فقط وقتی پلن سهمیه دارد) |
X-Quota-Remaining | باقیمانده سهمیه امروز |
X-Plan | نام پلن (URL-encoded) |
X-Local-Free-Remaining | فقط برای درخواست از صفحهای روی localhost یا 127.0.0.1: باقیمانده درخواستهای رایگان توسعه امروز |
Retry-After | در پاسخهای ۴۲۹ و ۵۰۳: چند ثانیه صبر کنید |
X-Request-Id | شناسه درخواست برای پیگیری با پشتیبانی |
HTTP/2 200
content-type: application/json
x-ratelimit-limit: 120
x-quota-limit: 200000
x-quota-remaining: 198157
x-plan: %D8%AD%D8%B1%D9%81%D9%87%E2%80%8C%D8%A7%DB%8Cتلاش دوباره درست
// تلاش دوباره با احترام به Retry-After و افزایش تدریجی فاصله
async function getPrices(url, key, tries = 4) {
for (let i = 0; i < tries; i++) {
const res = await fetch(url, { headers: { "X-API-Key": key } });
if (res.ok) return (await res.json()).data;
const { error } = await res.json();
// خطاهای 4xx (بهجز 429) با تکرار درست نمیشوند
if (res.status !== 429 && res.status < 500) throw new Error(error.code);
if (error.code === "daily_quota_exceeded") throw new Error(error.code);
const wait = Number(res.headers.get("Retry-After")) || 2 ** i;
await new Promise((r) => setTimeout(r, wait * 1000));
}
throw new Error("unavailable");
}مصرف کمتر، سرعت بیشتر
پاسخ را چند ثانیه در سرور کش کنید، فقط نمادهای لازم را با
symbols بخواهید و برای نمایش زنده بهجای polling از /v1/stream استفاده کنید.