حدود المعدّل

تحمي حدود المعدّل رصيدك والخدمة. تُحتسب الحدود بعدد الطلبات في الدقيقة (RPM) لكل مفتاح API، ويمكن للمفاتيح أيضًا أن يكون لها حد يومي للإنفاق بالدولار.

الحدود حسب الخطة

قم بالترقية من صفحة الأسعار لرفع حدّك.

الحدود الخاصة بكل مفتاح

عند إنشاء مفتاح أو تعديله في مفاتيح API يمكنك ضبط:

نافذة RPM مدتها دقيقة واحدة وتُحتسب لكل مفتاح على حدة، لذا لا تتشارك المفاتيح المنفصلة للتطبيقات المختلفة الحدّ نفسه، لكن كل مفتاح يبقى مقيّدًا بحد خطتك.

ترويسات حدود المعدل

كل استجابة توليد (ناجحة أو فاشلة) تخبرك بموقعك، لتبطئ قبل الوصول إلى الحد:

يمكن لعملاء المتصفح قراءتها أيضًا (مدرجة في Access-Control-Expose-Headers).

الذروة والطلبات المتزامنة

لا تُرفض الطلبات التي تتجاوز الحد فورًا: تنتظر في طابور وتبدأ بمجرد أن تتسع نافذة الدقيقة. يعمل حتى 10 طلبات لكل حساب في الوقت نفسه، وينتظر الباقي حتى ينتهي أحدها. قبل أن يبدأ الطلب تُحجز تكلفته القصوى المقدّرة من رصيدك مع تكلفة الطلبات الجارية، فلا تنفق الطلبات المتوازية أبدًا أكثر مما لديك. الطلب الذي لا يستطيع البدء خلال 60 ثانية يعيد 429 (rate_limited أو concurrency_limit) مع Retry-After، والطلب الذي لم تعد تكلفته تتسع لرصيدك يعيد 402 insufficient_balance.

إعادة محاولة آمنة باستخدام Idempotency-Key

بعد خطأ في الشبكة قد لا تعرف إن كان الطلب قد وصل. أرسل ترويسة Idempotency-Key (سلسلة فريدة حتى 120 حرفًا، مثل UUID) وأعد المحاولة بالمفتاح نفسه: إذا كان الطلب الأول قد أُرسل إلى النموذج بالفعل، تعيد المحاولة 409 idempotency_conflict بدل تنفيذ المهمة واحتسابها مرتين. وإذا فشل الطلب الأول قبل الوصول إلى النموذج يُحرَّر المفتاح وتعمل المحاولة بشكل طبيعي. يُستخدم المفتاح مرة واحدة لكل حساب خلال 24 ساعة.

curl https://api14.com/api/v1/images/generations \
  -H "Authorization: Bearer $API14_KEY" \
  -H "Idempotency-Key: 6f1c2a3e-order-1842" \
  -H "Content-Type: application/json" \
  -d '{"model": "black-forest-labs/flux-3-image", "prompt": "a red bicycle"}'

عند بلوغ أحد الحدود

طلبات كثيرة جدًا

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "message": "Rate limit of 5 requests per minute exceeded.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

انتظر عدد الثواني المحدد في Retry-After، ثم أعِد المحاولة. تعيد حِزم OpenAI SDK الرسمية محاولة استجابات 429 تلقائيًا مع تراجع تدريجي (محاولتان افتراضيًا؛ ويمكن ضبط ذلك عبر maxRetries / max_retries).

حد الإنفاق اليومي

{
  "error": {
    "message": "This API key reached its daily spend limit.",
    "type": "rate_limit_error",
    "code": "daily_limit_reached"
  }
}

لن تفيد إعادة المحاولة حتى يوم UTC التالي. ارفع الحد اليومي للمفتاح أو أزِله من مفاتيح API إذا كانت هذه حركة مرور متوقعة.

حدود المزوّد الأصلي

لدى المزوّدين حدودهم الخاصة، وهي أكثر صرامة مع متغيّرات النماذج :free. عندما يفرض مزوّد حدًّا على طلب ما، يُمرَّر إليك خطأ 429 الخاص به. استخدم النماذج الاحتياطية أو توجيه المزوّدين لتوزيع الحمل على عدة مزوّدين.

التعامل مع الحدود في الكود

• احترم Retry-After وأعِد المحاولة مع تراجع أُسّي وعشوائية (jitter).
• ميّز بين rate_limited (أعِد المحاولة لاحقًا) وبين daily_limit_reached وinsufficient_balance (إعادة المحاولة لا تفيد).
• ضع المهام الخلفية في طابور بدلًا من إطلاقها جميعًا دفعة واحدة.
• استخدم البث للاستجابات الطويلة: الطلب المبثوث الواحد يُحتسب طلبًا واحدًا.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api14.com/api/v1", api_key="sk-api14-...", max_retries=0)

for attempt in range(5):
    try:
        r = client.chat.completions.create(model="openai/gpt-5-mini", messages=[{"role": "user", "content": "Hi"}])
        break
    except RateLimitError as e:
        if e.code == "daily_limit_reached":
            raise
        time.sleep(int(e.response.headers.get("retry-after", 2 ** attempt)))

راجع الأخطاء للاطلاع على كل رموز الحالة.