Docsمنصة مفتوحةالتوثيق والحد من المعدل

التوثيق والحد من المعدل

Bearer / X-API-Key / query three writing methods, package rate limit, HTTP status code semantics.

All endpoints of the open platform are uniformly authenticated through API Key. وتوضح هذه الصفحة بوضوح الطرق الثلاثة لكتابة الأسماء، والحدود القصوى لمعدلات الطرد، والثغرات الرطبة للرد على الأخطاء.

ثلاثة أساليب لكتابة التوثيق

1 - الإذن: الدب (التوصية)

bash

curl https://braidrun.com/api/v1/workflows \
  -H "Authorization: Bearer dyk_<id>_<secret>"

The most standard writing method, supported by all SDKs by default. وتُفضَّل بيئة الإنتاج.

2.X-API-Key Header

bash

curl https://braidrun.com/api/v1/workflows \
  -H "X-API-Key: dyk_<id>_<secret>"

مناسب للسيناريوهات التي لا يمكن فيها لوكالة بعض الشبكات المغلقة أن تتقدم برئيس الترخيص. (مكافئ وظيفي لـ(بيرر.

3. Query parameter ?api key= (only in scenarios where Header cannot be written)

text

https://braidrun.com/api/webhook-trigger/approval/appr-123/approve?api_key=dyk_<id>_<secret>

استخدام المعلمات الاستفسار بحذر

وستُسجل المعلمات الحجر في تاريخ المصفوفين، وقائد المرفأ، وسجلات دخول خواديم شركة HTTP، وسجلات شبكة CDN. ولا يُستخدم إلا في سيناريوهات يجب أن تُطلق في شكل وصلات شبكية (مثل وصلات الموافقة بالبريد الإلكتروني/Slack/Telegram 1-click)، ويُستخدم بمفتاح قصير لشبكة نقل التكنولوجيا. لا تتخلى أبداً عن أولوية (بير) لالمعلمات الإستفسار.

الأولوية

Authorization: Bearer dyk_…
X-API-Key: dyk_…
?api_key=dyk_…

حاول من أعلى إلى أسفل وتوقف عن الثرثرة عندما تجد واحد غير فارغ.

تحديد المعدل

كل مُفتاح "أي بي آي" لديه حدين أعلى من "في الدقيقة" و "دايلي" التي تُطبق تلقائياً وفقاً لحزمة المالك الرئيسي. ولكل مفتاح حصة مستقلة ولا يتقاسمها مع مفاتيح أخرى في الحساب نفسه.

جدول المقارنة

التعبئة	دقيقة	يومية
Free	60	2,000
Pro	300	50,000
Team	1,200	500,000
Enterprise	6,000	أي شيء

النوافذ السيمانية

نافذة دقيقة · استخدام الدقائق الخبيثة كمفتاح، والحدود يعاد ترتيبها تلقائياً كل دقيقة (وليس نافذة الإنزلاق من أول نداء)
يومية (نافذة يومية) · استخدام تاريخ النقل غير المنسَّق كمفتاح، وإعادة التشغيل التلقائي في الساعة 00/00 من كل يوم

عند بلوغ الحد

http

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 60
X-RateLimit-Window: minute
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "window": "minute",
  "limit": 60,
  "retryAfterSeconds": 38
}

The client should:

اقرأ العنوان (عدد الثواني) وتأخر المدة المقابلة ثم حاول مرة أخرى
X-RateLimit-Window يخبرك أي نافذة ضُربت (دقيقة/يوم)
التراجع المفاجئ + جليس، لا تتراجع مباشرة بعد تلقي 429

مفاتيح متعددة لتقسيم حركة المرور

أتحتاجين إلى مدخل أعلى؟ وتصدر مفاتيح مستقلة لمختلف البيئات/التكامل المتباين، ويحصل كل مفتاح على حصة كاملة. A Pro user opening 3 Keys equals a total capacity of 900 RPM. هذا هو أفضل ممارسة لموقع الحوادث - عندما تحدث مشكلة، أنت فقط بحاجة للنظر في أي مفتاح له استخدام غير طبيعي.

HTTP response code

رمز الحالة	المعنى	استراتيجيات التكيف
`200`	النجاح	—
`202`	مقبولة (عندما يبدأ التنفيذ)	وضع تنفيذ المعاد
`400`	هيئة الطلب غير المستوفية (JSON/field error)	طلب ثابت؛ لا يعاد النظر
`401`	Token is missing/wrong format/revoked/expired/insuffic	Re check Token and scope; do not try again
`403`	تم تعطيل حساب المالك المكسور/غير مقفل	اتصل بمدير حساباتك، لا تحاول مرة أخرى
`404`	الموارد غير موجودة أو ليس لها مكانة بارزة	تفحص هويّة/مقعد، لا تُعيد
`409`	(مثلاً، تقررت الموافقة)	تحديد الوضع الحالي مرة أخرى
`429`	تحديد المعدل	Retry after comply with Retry-After
`500/502/503`	خطأ سيرفر	تراجع مفاجئ + جليس، إعادة 3-5 مرات

لماذا لا يفرق 401 بين الأسباب

Token missing, expired, revoked, and insufficient scope all return 401 uniformly, without exposing the specific failure reason - this avoids attackers from using trial and error to detect which key exist/which scopes are enabled. ويُحتفظ في سجل مراجعة الحسابات بسبب الفشل الكامل (مجال المعقول) ويمكن أن يفحصه المدير.