reason في استجابة 429 لتعرف أي حد أوقف الطلب، ثم انتظر Retry-After أو غيّر الحد. يقلّل التوجيه والبدائل الاحتياطية إخفاقات المزوّدين، لكن قد يظل الطلب مقيّدًا من جانب مزوّد أو بسياسة لمساحة العمل أو المفتاح.
تُرجع كل هذه الحدود
429. إذا تعذّر فرض حصص الـ Gateway لفترة وجيزة، يُرجع الـ Gateway بدلًا من ذلك 503 مع إرشادات لإعادة المحاولة.
حدود الـ Gateway
لكل مستخدم في كل مساحة عمل حصة من الطلبات في الدقيقة، تُقاس على مدى دقيقة متحركة. تتشارك مفاتيح API التي أنشأها المستخدم نفسه هذه الحصة. وتُحتسب طلبات OAuth على المستخدم المسجّل دخوله، وتتشارك المفاتيح التي ليس لها مالك حصة واحدة لمساحة العمل. ترتفع الحصة تلقائيًا كلما ترسّخت مساحة العمل. تحصل مساحة العمل على أعلى صف تستوفي شروطه، وتسري التغييرات خلال بضع دقائق:
للنماذج المجانية أيضًا حصة افتراضية قدرها 1,500 طلب لكل يوم بتوقيت UTC. وهي مشتركة بين جميع النماذج المجانية وبين كل مساحات العمل التي يرسل فيها المستخدم نفسه طلبات. لا تستهلكها طلبات النماذج المدفوعة. يُحتسب الطلب المجاني المقبول حتى إذا فشل المزوّد بعد ذلك، وتُحتسب البدائل الاحتياطية بين المزوّدين ضمن الطلب الواحد مرة واحدة.
ينطبق الحدّان عبر كل مناطق الـ Gateway، ويمكن رفعهما لمستخدم ومساحة عمل محددين. تستهلك عمليات الملفات واستطلاع حالة المهام حصة الدقيقة؛ أما نقاط نهاية الإدارة فلا تستهلكها.
يُرجع الطلب المرفوض
429 مع Retry-After بالثواني. انتظر هذه المدة قبل إعادة المحاولة.
حدود واجهة API للإدارة
تتشارك نقاط نهاية الإدارة، مثل/v1/keys و/v1/logs و/v1/analytics، حصة قدرها 200 وحدة في الدقيقة لكل بيانات اعتماد. لكل مفتاح إدارة ورمز OAuth وجلسة لوحة تحكم حصته الخاصة، وتتشارك الطلبات التي لا تحمل بيانات اعتماد حصة واحدة لكل عنوان IP. لا تستهلكها نقاط نهاية النماذج والملفات والدُفعات والمهام.
يستهلك كل طلب وحدات بحسب مقدار العمل الذي يتطلبه:
إن
/v1/health وطلبات CORS التمهيدية مجانية. يُرجع الطلب الذي يتجاوز الحصة 429 مع rate_limit_exceeded، والسبب management_api_rate_limit، وRetry-After: 60. العدّ تقريبي ولا تحمل هذه الاستجابات ترويسات x-ratelimit-*، لذا وزّع السكربتات الجماعية على فترات بدلًا من تشغيلها حتى الحد.
حدود المفاتيح والميزانيات
عند بلوغ حدود الطلبات أو الإنفاق اليومية أو الأسبوعية أو الشهرية لمفتاح API، أو ميزانيات مساحة العمل، يُرجع الطلب429 مع key_limit_exceeded. توضح الحقول reason وlimit_window وreset_at في الجسم أي حد بُلغ ومتى تُعاد فترته، ويعطي Retry-After عدد الثواني حتى ذلك الحين.
يغيب Retry-After عندما لا يُعاد ضبط الحد تلقائيًا، مثل ميزانية مدى الحياة أو مفتاح محظور حظرًا مرنًا. لا تُعد المحاولة: ارفع ميزانية مساحة العمل، أو ارفع حد المفتاح، أو استخدم مفتاحًا آخر.
يدير مالكو مساحة العمل ومسؤولوها الميزانيات باستخدام مفتاح إدارة عبر /v1/budgets أو من الإعدادات ← الميزانيات، التي تعرض لكل ميزانية الإنفاق حتى الآن، والنسبة المستخدمة، وتوقعًا للفترة، وموعد إعادة الضبط. تُعاد الميزانيات اليومية والأسبوعية والشهرية عند حدود UTC: منتصف الليل، ويوم الاثنين 00:00، واليوم الأول من الشهر.
يمكن أن تنبّه تنبيهات الإنفاق قبل بلوغ هذه الحدود. تُرجع قاعدة الإنفاق المضبوطة على الحظر 429 مع spend_rule_blocked. وهي تعمل بأفضل جهد وتبدأ بعد بضع دقائق من تجاوز الإنفاق حدها، لذا استخدم حدود المفاتيح والميزانيات للحصول على سقوف دقيقة. تعني الترويسة x-phaseo-spend-warning أن حظرًا قد يتبع.
ميزانيات الأقسام
يدير المالكون والمسؤولون ميزانيات الأقسام باستخدامphaseo department-budgets، أو واجهة /v1/department-budgets، أو من الإعدادات ← الميزانيات، أو بالمورد phaseo_department_budget في موفّر Terraform. يحتسب إنفاق القسم المفاتيح وطلبات OAuth نفسها التي تحتسبها حدود معدل الأقسام.
بعد أن يستنفد القسم ميزانيته اليومية أو الأسبوعية أو الشهرية، تُرجع طلبات مفاتيح API التي تُحتسب عليه 429 مع key_limit_exceeded والسبب department_daily_cost_budget_reached أو department_weekly_cost_budget_reached أو department_monthly_cost_budget_reached. يحدد الحقلان department_id وdepartment_name في الجسم القسم، ويوضح reset_at وRetry-After موعد إعادة ضبط ميزانيته.
- إذا تعذّر التحقق من الميزانية لفترة وجيزة، يُسمح بالطلبات، لذا قد يتجاوز القسم ميزانيته لوقت قصير.
- يتلقى المالكون والمسؤولون إشعارًا فوريًا على الهاتف عند نحو 80% من الميزانية ثم عند 100%. تُفحص الميزانيات لهذه التنبيهات كل 15 دقيقة، لذا قد تُرفض الطلبات قبل وصول تنبيه 100%.
سياسات حدود المعدل
يمكن لمسؤولي مساحة العمل إنشاء سياسات مسمّاة تضبطrequests_per_minute وtokens_per_minute وconcurrent_requests، وتعيينها للمفاتيح أو الأعضاء أو الأقسام أو المستخدمين النهائيين. أدِرها باستخدام phaseo rate-limits policies وphaseo rate-limits assignments، أو واجهة /v1/rate-limits، أو من الإعدادات ← حدود المعدل، أو بالمورديْن phaseo_rate_limit_policy وphaseo_rate_limit_assignment في موفّر Terraform.
ما الذي يُحتسب على القسم. يُحتسب المفتاح المرتبط بقسم على ذلك القسم وحده. ويُحتسب أي مفتاح آخر على كل قسم ينتمي إليه منشئه، وتُحتسب طلبات OAuth على كل أقسام مستخدمها. ويُحتسب العضو الذي لديه تجاوز للقسم على قسم التجاوز وحده. لاحتساب هذه المفاتيح وطلبات OAuth على القسم الأساسي للشخص وحده، اضبط إسناد الأقسام على primary من الإعدادات ← الإشعارات، أو عبر
spend.department_attribution في PATCH /v1/notifications/settings باستخدام مفتاح إدارة. تستخدم ميزانيات الأقسام وقواعد الإنفاق الإعداد نفسه.
عند انطباق عدة سياسات، تُحتسب كل منها، وأول سياسة تُستنفد ترفض الطلب. تنطبق السياسات إضافةً إلى حدود الـ Gateway. تسري تغييرات السياسات خلال دقيقة تقريبًا؛ وقد تستغرق تغييرات عضوية الأقسام التي تُجرى في لوحة التحكم أو عبر SCIM ما يصل إلى خمس دقائق تقريبًا.
الطلبات والـ tokens في الدقيقة
يُقاس كلاهما على دقيقة متحركة. تحتسبtokens_per_minute الـ tokens الداخلة والخارجة لكل طلب عند اكتماله، بما في ذلك الطلبات المتدفقة والفاشلة التي استهلكت tokens. يُرفض الطلب بمجرد أن يبلغ الاستهلاك خلال الدقيقة الأخيرة الحد، لذا قد تتجاوزه الطلبات الجارية بالفعل. تُحتسب البدائل الاحتياطية بين المزوّدين ضمن الطلب الواحد مرة واحدة.
يُرجع الطلب المرفوض 429 مع rate_limit_exceeded، والسبب policy_requests_per_minute أو policy_tokens_per_minute، وpolicy_id، وlimit_scope (key أو member أو department أو workspace أو end_user)، وRetry-After بالثواني.
تحمل الاستجابات للطلبات التي تشملها سياسة ترويسات الحد الأكثر تقييدًا:
لا يحمل الطلب المرفوض إلا ترويسات الحد الذي رفضه. يجري العدّ في الخلفية، لذا فإن
remaining تقريبية، ولا تتضمن ترويسات الـ tokens بعدُ استهلاك الطلب الحالي نفسه.
الطلبات المتزامنة
يحدّconcurrent_requests من عدد الطلبات التي يمكن أن تكون قيد التنفيذ في الوقت نفسه. يشغل الطلب خانة منذ قبوله حتى تُرسل استجابته كاملة، بما في ذلك الاستجابة المتدفقة كلها؛ وتتشارك البدائل الاحتياطية بين المزوّدين والنماذج ضمن الطلب تلك الخانة. عندما تكون كل الخانات مشغولة، يُرفض الطلب بالسبب policy_concurrent_requests مع Retry-After: 1.
يتطلب التحقق من حد التزامن انتظار عدّاد السياسة، ما يضيف زمن انتقال بسيطًا. تتحرر الخانة التي فُقد إطلاقها تلقائيًا بعد 15 دقيقة. لا تُقيَّد الدفعات وجلسات الوقت الفعلي، ولا يشغل إنشاء الفيديو خانة إلا أثناء الطلب الذي يبدؤه.
السياسات الصارمة
افتراضيًا، تسمح السياسة بالطلب عند الإخفاق: إذا تعذّر التحقق من حدودها، يُسمح بالطلب. اضبطfail_closed لجعلها صارمة. تتحقق السياسة الصارمة من حدود الطلبات والـ tokens قبل إرسال الطلب لا في الخلفية، ما يجعلها دقيقة لكنه يضيف زمن انتقال. إذا تعذّر التحقق منها خلال ثانيتين، يُرفض الطلب بالسبب policy_unavailable.
لا تحمل حالات الرفض بسبب التزامن أو policy_unavailable ترويسات x-ratelimit-*.
حدود المزوّد
تستخدم طلبات BYOK حدود حسابك لدى المزوّد. وتستخدم الطلبات المُدارة سعة مشتركة لدى المزوّد، وهي ليست حصة مخصصة لمساحة عملك. يمرّر Phaseo قيمةRetry-After بعد التحقق منها عندما يرسلها المزوّد. قد تتضمن استجابات BYOK أيضًا ترويسات X-Phaseo-Upstream-RateLimit-*؛ وتُحذف من الطلبات المُدارة لأنها تصف سعة مشتركة. لا تُمرَّر ترويسات المزوّد الأخرى. راجع رموز الأخطاء لرموز 429 الخاصة بالمزوّد.
التعامل مع طلب مقيّد
- اقرأ رمز الخطأ للتمييز بين التقييد المؤقت وحدّ أو ميزانية أو سياسة تحتاج إلى تغيير في الإعدادات.
- التزم بـ
Retry-Afterعند وجوده. قد يكون ثواني أو تاريخ HTTP؛ تحقّق منه قبل جدولة إعادة المحاولة. - وإلا، فاستخدم تراجعًا أُسّيًا مع تذبذب عشوائي وحد أقصى للتأخير.
- قيّد إعادة المحاولة بعدد المحاولات وبمهلة إجمالية. ألغِ العمل المتروك وحرّر جسم كل استجابة فاشلة قبل إعادة المحاولة.
- قلّل التزامن إذا استمر التقييد.
429 حسب نقطة النهاية والنموذج، وافحص تكرار البدائل الاحتياطية في سجلات الطلبات. قارنها مع إعدادات التوجيه، ومع حصص حسابك لدى المزوّد بالنسبة إلى حركة BYOK. تتحكم ضوابط الحماية في المفاتيح التي يمكنها استخدام كل نموذج ومزوّد.