حدود المعدل

تعرّفوا على حدود طلبات الواجهة البرمجية واستخدام الأرصدة وكيفية التعامل مع تقييد المعدل بسلاسة.

الحدود الحالية

حصص الطلبات والأرصدة ضوابط منفصلة. تبلغ الحصة الافتراضية لمفاتيح API ‏60 طلبًا في الدقيقة و5,000 طلب في اليوم. وتتحكم هذه الحصص في سرعة استدعاء التكامل المصادق عليه للواجهة البرمجية. أما أرصدة الحساب فتتحكم في عدد عمليات التحقق التي يمكن تشغيلها.

للعمل على القوائم الكبيرة الحجم، تقبل /api/batch ما يصل إلى 500 بريد إلكتروني في طلب واحد. ويخضع رفع ملفات CSV بالجملة للأرصدة لا لعدد الطلبات: يجب أن يتوفر في الحساب رصيد كافٍ لعدد عناوين البريد في الملف المرفوع قبل أن تبدأ مهمة التحقق.

تقتصر أداة الفحص المجهولة العامة على 5 عمليات فحص يوميًا لكل عنوان IP. لقواعد رصيد الحساب، راجعوا الأرصدة والاستخدام. للاستيرادات الكبيرة، استخدموا التحقق بالجملة؛ ولسلوك التكامل، راجعوا معالجة الأخطاء, البدء السريع، و الأسعار.

استجابة تجاوز حد المعدل

عندما يتجاوز مفتاح API حصة طلباته، تُرجع الواجهة البرمجية استجابة 429 Too Many Requests . وتتضمن الاستجابة Retry-After ليعرف العميل المدة التي ينبغي انتظارها قبل إعادة المحاولة.

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after the indicated delay.",
  "status_code": 429,
  "retry_after": 15
}

ترويسة Retry-After

أما Retry-After تشير ترويسة الاستجابة إلى عدد الثواني التي يجب انتظارها قبل إعادة محاولة طلب بمفتاح API تجاوز حصته:

HTTP/1.1 429 Too Many Requests
Retry-After: 15
Content-Type: application/json

التعامل مع حدود المعدل في الشيفرة

اقرأوا الترويسة أولًا، وانتظروا عدد الثواني المحدد، ثم أعيدوا المحاولة. إذا كانت الترويسة غائبة، فاستخدموا مهلة احتياطية متحفظة.

import requests, time

def verify_with_retry(email, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://verimails.com/api/verify/single",
            headers={"Authorization": f"Bearer {api_key}"},
            json={"email": email}
        )

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 15))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        response.raise_for_status()

    raise Exception("Max retries exceeded")

أفضل الممارسات

• أبقوا تكاملات API المصادق عليها دون 60 طلبًا في الدقيقة و5,000 طلب في اليوم، ما لم تكن لحسابكم حدود مختلفة.
• احرصوا على أن تبقى حمولات /api/batch عند 500 بريد إلكتروني أو أقل.
• التزموا دائمًا بترويسة Retry-After عندما يتلقى طلب بمفتاح API الرمز 429.
• تحققوا من الأرصدة المتاحة قبل بدء عملية تحقق كبيرة.
• استخدموا التحقق بالجملة لقوائم CSV، وتأكدوا من أن الحساب يملك أرصدة كافية لعدد عناوين البريد في الملف.