حدود معدل استدعاءات API وأفضل الممارسات

يحصل كل مفتاح Ody API على 600 طلب في الدقيقة عبر /v1/api/* ونقطة نهاية MCP — اقرأ رؤوس RateLimit-* في كل استجابة، وتراجع باستخدام قيمة Retry-After عندما تتلقى 429.

كيف يعمل الحد

• الحد هو لكل مفتاح، ويتم احتسابه في نافذة ثابتة مدتها 60 ثانية. الطلبات بدون مفتاح صالح يتم تحديدها لكل عنوان IP بدلاً من ذلك.
• يحمل كل رد — سواء كان ناجحًا أو خطأً — ثلاثة رؤوس قياسية:
  • RateLimit-Limit — ميزانيتك في الدقيقة (600).
  • RateLimit-Remaining — الطلبات المتبقية في النافذة الحالية.
  • RateLimit-Reset — الثواني المتبقية حتى إعادة تعيين النافذة.
• تجاوز الحد يعيد 429 مع رمز الخطأ resource_exhausted ورأس Retry-After (بالثواني). انتظر على الأقل هذه المدة قبل إعادة المحاولة.

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

البقاء ضمن الحد

• راقب RateLimit-Remaining وقم بالتباطؤ بشكل استباقي عندما يقترب من الصفر، بدلاً من التفاعل مع استجابات 429.
• استخدم webhooks بدلاً من الاستقصاء (polling). اشترك بنقطة نهاية للأحداث مثل message.received وسيقوم Ody بدفع النشاط إليك — انظر استقبال webhooks والتحقق من التوقيعات. إذا كان لا بد من الاستقصاء، فإن كل 10-30 ثانية كافية لصندوق وارد مشترك.
• أعد المحاولة بتراجع أسي (exponential backoff) واهتزاز (jitter) عند 429 و 5xx، مع تحديد سقف لإعادة المحاولات. احترم Retry-After عند وجوده. بالنسبة لعمليات الإرسال، قم بإقران إعادة المحاولات بمفتاح Idempotency-Key لضمان عدم إرسال أي شيء مرتين — انظر التقسيم، الثبات، ومعالجة الأخطاء.
• اطلب صفحات أكبر (?limit= حتى الحد الأقصى لكل نقطة نهاية) بدلاً من العديد من الصفحات الصغيرة عند مزامنة البيانات.

أفضل ممارسات أمان المفاتيح

• حدد نطاق كل مفتاح للحد الأدنى الذي يحتاجه. قم بإلغاء تحديد النطاقات عند الإنشاء — يجب أن تحتوي لوحة التحكم التي تقرأ المحادثات فقط على conversations:read. انظر الحصول على مفتاح Ody API الخاص بك.
• استخدم مفاتيح الاختبار في كل مكان قد تكون فيه الرسائل النصية الحقيقية خطأً. يجب أن تعمل بيئات التطوير و CI على مفاتيح ody_test_… بحيث يتم محاكاة إرسال الرسائل — انظر الإنشاء بأمان باستخدام وضع الاختبار.
• مفتاح واحد لكل تكامل. مفاتيح منفصلة لـ Zapier، وخادمك، ومساعد AI تعني أنه يمكنك إلغاء مفتاح واحد دون تعطيل الآخرين، ويبقى عمود "آخر استخدام" في الإعدادات ← Developer API ذا معنى.
• احتفظ بالمفاتيح على جانب الخادم. لا تقم أبدًا بتضمين مفتاح في تطبيقات الهاتف المحمول، أو JavaScript المتصفح، أو المستندات المشتركة — يمكن لأي شخص لديه المفتاح التصرف كمنشئه ضمن نطاقاته.
• قم بتدوير المفاتيح وتقليمها. قم بإلغاء المفاتيح التي لم تعد تستخدمها. نظرًا لأن النص العادي يظهر مرة واحدة فقط، فإن التدوير يعني إنشاء مفتاح جديد، نشره، ثم إلغاء المفتاح القديم.

مقالات ذات صلة

• نظرة عامة على API والمصادقة
• التقسيم، الثبات، ومعالجة الأخطاء
• استقبال webhooks والتحقق من التوقيعات
• الإنشاء بأمان باستخدام وضع الاختبار