معالجة الأخطاء

يشرح هذا الدليل تنسيق استجابة الأخطاء في 诺玛AI، وسيناريوهات الأخطاء الشائعة، واستراتيجيات المعالجة المُوصى بها.

تنسيق استجابة الأخطاء#

تتبع جميع استجابات الأخطاء تنسيق JSON موحدًا:

{
  "error": {
    "code": "invalid_api_key",
    "message": "مفتاح API المُقدَّم غير صالح، يُرجى التحقق منه وإعادة المحاولة.",
    "type": "authentication_error"
  }
}

رموز حالة HTTP#

رمز الحالة

النوع

الوصف

هل تجب إعادة المحاولة

`400`

`invalid_request_error`

خطأ في معاملات الطلب

❌ عدّل المعاملات ثم أعد المحاولة

`401`

`authentication_error`

مفتاح API غير صالح أو مفقود

❌ تحقق من مفتاح API

`403`

`permission_error`

الصلاحيات غير كافية

❌ تحقق من صلاحيات الحساب

`404`

`not_found_error`

النموذج أو المورد غير موجود

❌ تحقق من معرّف النموذج

`429`

`rate_limit_error`

تم تجاوز حد المعدل

✅ انتظر ثم أعد المحاولة

`500`

`internal_error`

خطأ داخلي في الخادم

✅ أعد المحاولة لاحقًا

`502`

`upstream_error`

خطأ من مزود النموذج الأعلى

✅ غيّر النموذج أو أعد المحاولة

`503`

`service_unavailable`

الخدمة غير متاحة مؤقتًا

✅ أعد المحاولة لاحقًا

الأخطاء الشائعة وحلولها#

401 — مفتاح API غير صالح

{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

الحل:

• تحقق من نسخ مفتاح API بشكل صحيح (بما في ذلك بادئة `sk-`)
• تأكد من أن المفتاح لم تنتهِ صلاحيته ولم يُعطَّل
• تحقق من تحميل متغيرات البيئة بشكل صحيح

429 — حد المعدل

الحل:

• تحقق من `x-ratelimit-reset-requests` في ترويسة الاستجابة
• طبّق إعادة المحاولة بالتراجع الأسي
• إذا احتجت إلى حصة أعلى، تواصل مع الدعم لطلب التعديل

502 — خطأ من الأعلى

الحل:

• استخدم التراجع عند الفشل للتبديل تلقائيًا إلى نموذج بديل
• أعد المحاولة لاحقًا
• تحقق من صفحة حالة مزود النموذج

استراتيجية إعادة المحاولة#

يُوصى باستخدام استراتيجية **التراجع الأسي (Exponential Backoff)**:

import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<APINOMA_API_KEY الخاص بك>"
)

def chat_with_retry(max_retries=5, **kwargs):
    """غلاف إعادة المحاولة بالتراجع الأسي"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)

        except RateLimitError:
            # 429: انتظر ثم أعد المحاولة
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"تم تجاوز حد المعدل، الانتظار {wait:.1f}s ثم إعادة المحاولة...")
            time.sleep(wait)

        except APIConnectionError:
            # خطأ في الشبكة: انتظر قليلًا ثم أعد المحاولة
            wait = 2 ** attempt
            print(f"خطأ في الاتصال، الانتظار {wait}s ثم إعادة المحاولة...")
            time.sleep(wait)

        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: خطأ في الخادم، أعد المحاولة
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: خطأ من العميل، لا تُعد المحاولة
                raise

    raise Exception(f"ما زال الفشل قائمًا بعد {max_retries} محاولات")

# الاستخدام
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "مرحبا"}]
)

ضبط المهلة#

يُنصح بضبط مهلة زمنية معقولة لاستدعاءات API:

# Python OpenAI SDK
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<APINOMA_API_KEY الخاص بك>",
    timeout=60.0,  # مهلة 60 ثانية
    max_retries=3  # إعادة المحاولة المدمجة في SDK
)

يُنصح باستخدام مهلة أطول للطلبات المتدفقة (120-300 ثانية)، لأن النموذج قد يحتاج وقتًا أطول لتوليد المحتوى الكامل.

أفضل الممارسات#

• ميّز بين الأخطاء القابلة لإعادة المحاولة وغير القابلة لها — 4xx تتطلب عادةً تعديل الطلب، و5xx يمكن إعادة محاولتها
• استخدم التراجع الأسي — لتجنب إعادة المحاولة المتكررة عند تجاوز حد المعدل
• اضبط عددًا أقصى لإعادة المحاولة — لمنع إعادة المحاولة اللانهائية
• سجّل سجلات الأخطاء — لتسهيل تشخيص المشكلات
• اضبط التراجع عند الفشل — استخدم معامل `provider.fallback` في 诺玛AI للتبديل التلقائي بين النماذج
• راقب معدل الأخطاء — تابع اتجاهات الأخطاء في لوحة التحكم

آخر تحديث في 23 يونيو 2026