تُرجع الواجهة رمز حالة HTTP عاديًا ورمز خطأ قابلًا للقراءة آليًا. اختر خطوتك التالية بناءً على رمز الحالة. يتبع هذا الجدول المرجع التقني لدى BroadNet.
| رمز الحالة | المعنى | ما العمل |
|---|---|---|
| 400 / 422 | طلب أو حقل غير صالح | أصلح الطلب أولًا |
| 401 | مفتاح مفقود أو غير صالح أو منتهي الصلاحية، أو ميزانية دفع حسب الاستخدام محظورة، أو حصة مستنفدة | تحقّق من حالة المفتاح ورصيد الحساب |
402 insufficient_balance |
لا يكفي رصيد الحساب لعملية شراء؛ يتضمّن الجسم الرصيد والسعر | موّل الحساب، ثم أعد المحاولة |
| 403 | رفضته سياسة النموذج أو المسار أو عناوين IP | أصلح عدم التطابق، مثل قائمة عناوين IP المسموح بها |
| 409 | تعارض مع حالة الحساب: mint_in_progress أو key_limit_reached أو credential_limit_reached أو key_pending |
أعد المحاولة في حالة mint_in_progress فقط، وبنفس request_id |
| 413 | الطلب كبير جدًا؛ الحد الأقصى لملفات التفريغ الصوتي 26,214,400 بايت | صغّر الطلب |
| 429 | بلوغ حد المعدل أو التزامن أو معدل الرموز أو الإنفاق | اقرأ تفاصيل الاستجابة، وانتظر مدة متزايدة، ثم أعد المحاولة |
| 500 / 502 / 503 / 504 | معالجة من جهة الخادم | أعد المحاولة مع انتظار أُسّي له حد أقصى؛ واستخدم نفس request_id عند شراء المفاتيح بالساعة |
تنص وثائق BroadNet على فحص رمز حالة HTTP قبل تحليل جسم JSON، ثم قراءة رمز error القابل للقراءة آليًا حيثما وُجد.
ما الحدود التي تسبّب الخطأ 429؟
يسمح مفتاح الدفع حسب الاستخدام بما يصل إلى 30 من الطلبات في الدقيقة و4 من الطلبات قيد التنفيذ في آنٍ واحد. وتمنح وثائق BroadNet المفتاح بالساعة 120 من الطلبات في الدقيقة وتدفقًا واحدًا و300,000 من الرموز (التوكنات) في الدقيقة. أما في الخطة غير المحدودة، فكل جلسة تنفّذ طلبًا واحدًا في كل مرة. ولمقارنة هذه الحدود بحدود OpenAI وAnthropic وGroq وDeepSeek، اقرأ حدود معدل LLM API لدى كل مزوّد.
كيف أعيد المحاولة باستخدام OpenAI SDK؟
تعيد حزمة OpenAI Python SDK بالفعل محاولة أخطاء الاتصال واستجابات 408 و409 و429 و5xx مرتين افتراضيًا، مع انتظار أُسّي قصير، بحسب ملف README على GitHub. ومهلتها الافتراضية 10 دقائق. اضبط القيمتين صراحةً:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
max_retries=4, # 0 turns automatic retries off
timeout=120, # seconds; raise it for long reasoning answers
)
كيف أكتب آلية انتظار خاصة بي؟
إذا استدعيت الواجهة دون حزمة SDK، فضع حدًا أقصى لعدد المحاولات ولمدة الانتظار معًا:
import random, time, requests
RETRY = {429, 500, 502, 503, 504}
def post_with_backoff(url, headers, body, tries=5):
for attempt in range(tries):
r = requests.post(url, headers=headers, json=body, timeout=120)
if r.status_code not in RETRY:
return r # success, or an error to fix rather than retry
time.sleep(min(30, 2 ** attempt) + random.random())
return r
لا تُعد أبدًا محاولة 400 أو 403 أو 413 أو 422 دون تعديل: الطلب نفسه سيفشل بالطريقة نفسها. وكل إعادة لطلب محادثة هي عملية استدلال جديدة تُحتسب مرة أخرى في الدفع حسب الاستخدام. راجع الانتظار الأُسّي (exponential backoff) للنمط العام.
إعادة محاولة شراء مفتاح بالساعة بأمان
يقبل POST /portal/keys/hourly قيمة request_id. بعد انتهاء المهلة، أو انقطاع الاتصال، أو الخطأ 409 mint_in_progress، أو 5xx، أعد المحاولة بنفس request_id. لا يؤدي تكرار request_id أبدًا إلى إنشاء مفتاح ثانٍ أو تحصيل ثمنه؛ بل يُرجع التكرار already_issued: true والاسم المستعار للمفتاح. ولا تولّد معرّفًا جديدًا أبدًا قبل أن تعرف نتيجة الطلب الأول. المزيد عن مفاتيح منع التكرار (idempotency keys).
حل المشكلات
- 401 مباشرة بعد شحن الرصيد. تعرض صفحة الحساب في BroadNet آخر حصة مسجّلة، وتَسِم أي تغيير في التمويل بأنه قيد التحديث أثناء تطبيقه. حدّث الصفحة وأعد المحاولة بعد اكتماله.
- 429 مع طلبات قليلة في الدقيقة. الأرجح أنك تصطدم بحد التزامن البالغ 4 من الطلبات، مثلًا مع عمليات بث طويلة تعمل بالتوازي. استخدم مجموعة عمّال (worker pool) صغيرة.
- 403 على نموذج دون آخر. سياسة المفتاح لا تغطي ذلك النموذج أو المسار. فمفاتيح الخطط مثلًا مخصّصة لـ
broadnet/deepseek-v4.1-flash، والمفتاح بالساعة لا يغطي إلاbroadnet/gemma-4-26b-a4b. - أعادت حزمة SDK المحاولة فدفعت مرتين. طلب المحادثة المعاد هو عملية استدلال جديدة. اضبط
max_retries=0حيث تكون الإجابة المكرّرة أعلى كلفة من الطلب الفاشل.
ماذا ترسل إلى الدعم
أرفق قيمة الترويسة X-Request-ID، والطابع الزمني بتوقيت UTC، والمسار، ورمز حالة HTTP، والاسم المستعار لمفتاحك. ولا ترسل المفتاح نفسه أبدًا. يوضّح دليل OpenAI Python SDK كيف تقرأ هذه الترويسة.
