حدود المعدّل

معدّل الطلبات

تُطبَّق الحدود على كل مفتاح API، وتحدد باقة مساحة العمل قيمها. لكل مفتاح حدّ في الثانية (نافذة منزلقة مدتها ثانية واحدة) وحصة يومية يُعاد ضبطها عند منتصف الليل بتوقيت UTC. لا تخضع جلسات لوحة التحكم لحدود المعدّل.

لا تُحتسب الطلبات المرفوضة بسبب نطاق أو وحدة مفقودة (403)؛ أما أي طلب يجتاز المصادقة فيُحتسب، أيًّا كانت نتيجته.

الترويسات

تحمل كل استجابة اجتازت محدِّد المعدّل الرصيد المتبقي من الطلبات. X-RateLimit-Limit وX-RateLimit-Remaining تصفان نافذة الثانية الواحدة؛ ويظهر زوج Daily عندما تكون للمفتاح حصة يومية.

HTTP/2 200X-RateLimit-Limit: 20X-RateLimit-Remaining: 19X-RateLimit-Daily-Limit: 100000X-RateLimit-Daily-Remaining: 98431

كيف تبدو استجابة 429

يُرجع الطلب المقيَّد 429 مع الرمز rate_limit_exceeded، وغلاف الخطأ القياسي، وترويسة Retry-After بعدد صحيح من الثواني. انتظر هذه المدة على الأقل قبل إعادة المحاولة، وطبّق تراجعًا أسّيًا إذا قُيِّد طلبك مرة أخرى.

HTTP/2 429Content-Type: application/jsonRetry-After: 1 {"code":"rate_limit_exceeded","message":"API key rate limit exceeded.","requestId":"3f2b6c1e-…","retryable":true}

عند استنفاد الحصة اليومية تكون الإجابة 429 مع الرمز daily_quota_exceeded وقيمة Retry-After تَعُدّ حتى منتصف الليل بتوقيت UTC. لا تُرسل ترويسات الحصة مع استجابة 429 نفسها.

وحدات الرصيد

بمعزل عن معدّل الطلبات، تُحتسب كل قراءة بوحدات رصيد من محفظة مساحة العمل. القراءات المخزنة مؤقتًا منخفضة التكلفة، أما الطلب الذي يجمع بيانات جديدة فيكلّف أكثر (راجع وحدات الرصيد). عند بلوغ الحد الأقصى، يُرجع كل استدعاء محتسَب، بما في ذلك القراءات المخزنة مؤقتًا، 402 مع الرمز credit_cap_exceeded.