أكواد الأخطاء

تُعاد كل الأخطاء برمز HTTP صريح وجسم JSON. تتبع الصيغة الواجهة المستدعاة: OpenAI على /v1، Anthropic على /anthropic.

جدول الأكواد#

HTTP	الكود	السبب	ماذا تفعلون
400	`invalid_request_error`	جسم JSON غير صالح، معامل خارج النطاق، سياق طويل جدًا، محتوى غير مدعوم (صورة، مستند).	اقرؤوا `error.param` : يسمي الحقل المعني. صححوا الطلب.
401	`invalid_api_key`	مفتاح غائب، بصيغة خاطئة، غير معروف أو مُلغى.	تحققوا من الترويسة `Authorization: Bearer zir_ai_…`. أنشئوا مفتاحًا جديدًا عند الحاجة.
402	`insufficient_balance`	المحفظة فارغة، أو طلب سيتجاوز أقصى تكلفة لكل طلب أو الميزانية الشهرية المحددة على المفتاح.	اشحنوا على Top up : تُستأنف الخدمة فورًا، دون إعادة تشغيل. وإن كان الرصيد كافيًا فاضبطوا حدود المفتاح في API keys أو خفّضوا `max_tokens`.
403	`account_disabled`	الوصول إلى API معلَّق (إساءة استخدام، طلب من جانبكم)، أو طلب رفضته حدود المفتاح (نموذج أو نقطة وصول غير مسموح به، أو مفتاح معلَّق، أو مفتاح يحمل قائمة عناوين IP لا نستطيع تطبيقها حاليًا).	اقرؤوا `error.message` : يبيّن أي حدّ من حدود المفتاح ينطبق، ويُضبط في API keys. وإلا فاتصلوا بالدعم من المنصة.
404	`model_not_found`	اسم نموذج غير معروف أو نموذج مُعطَّل.	استخدموا `mina-flash` أو `mina-low` أو `mina-full` (GET /v1/models).
409	`invalid_request_error`	طلب لا يتوافق مع الحالة الراهنة : `Idempotency-Key` سبق استخدامه لدفعة أخرى، أو ملف غير متاح للعملية المطلوبة، أو رفض من المحركات المتاحة.	اقرؤوا `error.message` : يبيّن أي هذه الحالات تنطبق.
413	`invalid_request_error`	تجاوز في الحجم أو الحصة : جسم JSON، أو ملف مرفوع، أو مخرجات دفعة، أو طلب أكبر مما تقبله المحركات المتاحة (الحدود).	اقرؤوا `error.message` : يبيّن هل يتعلق الأمر بحجم طلب أم بحصة ملفات. قلّصوا الطلب، أو احذفوا ملفات لم تعد لازمة.
422	`invalid_request_error`	طلب لم تتمكن المحركات المتاحة من معالجته.	اقرؤوا `error.message` وصححوا الطلب : هذا الرفض ليس عابرًا، فلا فائدة من إعادة إرساله كما هو.
429	`rate_limit_exceeded`	تجاوز RPM أو الطلبات المتزامنة.	انتظروا `Retry-After` ثم أعيدوا المحاولة (الحدود).
500	`api_error`	خطأ داخلي في CloudZIR.	أعيدوا المحاولة. إن استمر الأمر، أرسلوا `X-Request-Id` إلى الدعم.
501	`not_implemented`	ميزة معلَنة لكنها غير متاحة بعد : لم يُربط بها أي محرك على هذه المنصة. ليس عطلًا عابرًا.	لا تعيدوا المحاولة : لا تحمل الاستجابة `Retry-After` أبدًا ولن تتغير النتيجة. اقرؤوا `error.message`، فهو يسمّي الميزة.
503	`overloaded`	سعة مشبعة أو لا محرك متاح لهذا الطلب.	أعيدوا المحاولة بعد `Retry-After`. لا يُفوتَر أبدًا.

صيغة استجابات الأخطاء#

واجهة OpenAI (`/v1`)#

{
  "error": {
    "message": "Solde insuffisant. Rechargez votre compte sur https://plateforme.cloudzir.com/topup.",
    "type": "insufficient_balance",
    "param": null,
    "code": "insufficient_balance"
  }
}

واجهة Anthropic (`/anthropic`)#

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Le champ 'max_tokens' est requis."
  }
}

تتعرف حزم SDK الرسمية لـOpenAI وAnthropic على هاتين الصيغتين وتُطلق استثناءاتها المعتادة (RateLimitError، AuthenticationError، إلخ).

الأخطاء أثناء البث المباشر#

إن وقع الحادث بعد أول بايت، لم يعد بإمكان التدفق تغيير رمز HTTP (أصبح 200 بالفعل). يصل الخطأ حينها كحدث :

data: {"error":{"message":"Erreur interne.","type":"api_error","param":null,"code":"api_error"}}

data: [DONE]

event: error
data: {"type":"error","error":{"type":"api_error","message":"Erreur interne."}}

عالجوا إذًا دائمًا حالة «يصل كائن error في منتصف التدفق».

المعالجة الموصى بها#

الفئة	إعادة المحاولة؟	الاستراتيجية
400، 404، 409، 413، 422	لا	خطأ في التطبيق: صححوا الطلب، سجّلوه.
401، 403	لا	مشكلة إعداد أو حساب: نبّهوا إنسانًا.
402	لا	نبّهوا المُشغِّل (الرصيد) وحوّلوا إلى قائمة انتظار.
501	لا	ميزة غير متاحة بعد : نتيجة الطلب ستبقى نفسها، فلا تعيدوا إرساله.
429، 500، 503	نعم	انتظار أُسي + jitter، من 3 إلى 5 محاولات.

from openai import OpenAI, APIStatusError, RateLimitError

client = OpenAI(api_key=cle, base_url="https://api.cloudzir.com/v1")

try:
    r = client.chat.completions.create(model="mina-low", messages=messages)
except RateLimitError:
    ...  # attendre puis réessayer
except APIStatusError as exc:
    if exc.status_code == 402:
        alerter("Solde CloudZIR épuisé")
    elif exc.status_code in (500, 503):
        ...  # réessayer
    else:
        raise  # 400, 404, 409, 413, 422 : bug applicatif

الحصول على المساعدة#

لأي خطأ غير مفهوم، أرسلوا من Help & Feedback : X-Request-Id، التوقيت الزمني UTC، النموذج والرمز المُستلَم. هذا ما يتيح إيجاد الأثر الدقيق من جهة الخادم.

استجابة API