الحساب

الأخطاء

قائمة كاملة برموز الأخطاء وحالات HTTP التي تُعيدها بوابة api14 بصيغة أخطاء OpenAI، مع معنى كل رمز وكيفية التعامل معه برمجيًا.

تستخدم الأخطاء صيغة أخطاء OpenAI، فتحوّلها حِزم الـ SDK الرسمية إلى استثناءاتها المعتادة (APIError وRateLimitError وAuthenticationError وغيرها). اعتمد على code في التفرّع؛ أما message فهو شرح مقروء باللغة الإنجليزية.

{
  "error": {
    "message": "This request may cost up to $0.0123 but your balance is $0.0040. Add funds at /pricing.",
    "type": "insufficient_quota",
    "code": "insufficient_balance"
  }
}

الطلبات الفاشلة لا تُحتسب عليك. أي استجابة برمز حالة 4xx أو 5xx لا تكلّفك شيئًا.

رموز أخطاء البوابة

الحالة	`code`	`type`	المعنى
400	`model_required`	`invalid_request_error`	الحقل `model` مفقود.
400	`invalid_json`	`invalid_request_error`	جسم الطلب ليس كائن JSON.
400	`invalid_body`	`invalid_request_error`	تعذّرت قراءة جسم الطلب من نوع multipart.
400	`max_tokens_too_large`	`invalid_request_error`	طلب تجريبي من ساحة التجربة (playground) طلب عددًا كبيرًا جدًا من tokens المخرجات.
401	`invalid_api_key`	`authentication_error`	المفتاح مفقود أو غير صالح الصيغة أو ملغى.
402	`insufficient_balance`	`insufficient_quota`	رصيدك بالدولار يساوي $0 أو أقل من التكلفة القصوى المقدّرة للطلب (المدخلات، حد المخرجات، الصور أو مدة الفيديو). لا يُرسل الطلب.
403	`model_not_allowed`	`permission_error`	قائمة النماذج المسموح بها للمفتاح لا تتضمن هذا النموذج.
403	`plan_required`	`permission_error`	خطتك لا تشمل فئة هذا النموذج.
404	`model_not_found`	`not_found_error`	معرّف النموذج غير معروف أو معطَّل أو محذوف.
404	`not_found`	`not_found_error`	نقطة نهاية غير معروفة، أو مهمة فيديو أو عملية توليد لا تخصّك.
413	`payload_too_large`	`invalid_request_error`	جسم الطلب يتجاوز حد الحجم (25 MB افتراضيًا).
429	`rate_limited`	`rate_limit_error`	تم تجاوز عدد الطلبات في الدقيقة. يأتي مع `Retry-After: 60`.
429	`daily_limit_reached`	`rate_limit_error`	بلغ المفتاح حدّه اليومي للإنفاق بالدولار.
409	`idempotency_conflict`	`api_error`	أُرسل طلب بهذا `Idempotency-Key` من قبل. استخدم مفتاحًا جديدًا لطلب آخر. حدود المعدل.
403	`site_not_allowed`	`permission_error`	للأدوات فقط: موقع الصفحة ليس ضمن مواقع الأدوات المسموح بها. الأدوات المضمّنة.
429	`widget_daily_limit`	`rate_limit_error`	للأدوات فقط: بلغت الأداة، أو جميع الأدوات معًا، حد الإنفاق اليومي بالدولار.
429	`visitor_daily_limit`	`rate_limit_error`	للأدوات فقط: بلغ هذا الزائر حد الطلبات اليومي المحدد في ضوابط الأدوات.
502	`upstream_unavailable`	`api_error`	تعذّر الوصول إلى المزوّد الأصلي.
4xx/502	`content_unavailable`	متغيّر	تعذّر جلب محتوى الفيديو حتى الآن (الحالة تعكس حالة المزوّد الأصلي، و502 إن لم توجد).
503	`maintenance`	`service_unavailable`	وضع الصيانة، نقاط نهاية التوليد متوقفة مؤقتًا، ونقاط نهاية `GET` لا تزال تعمل.
503	`not_configured`	`service_unavailable`	لم يتم إعداد البوابة بعد.

أخطاء المزوّد الأصلي

الأخطاء التي يُعيدها المزوّد الأصلي، مثل معامل غير صالح لنموذج معيّن، أو تجاوز طول السياق، أو رفض بسبب سياسة المحتوى، أو خطأ 429 خاص بالمزوّد، تُمرَّر برمز حالتها الأصلي وبصيغة { error: {... } } نفسها.

ما الذي يجب فعله

الحالة	إعادة المحاولة؟	الإجراء
400	لا	أصلِح جسم الطلب.
401	لا	تحقّق من المفتاح ومن ترويسة `Authorization: Bearer`. راجع المصادقة.
402	لا	أضف رصيدًا أو فعّل الشحن التلقائي.
403	لا	استخدم نموذجًا مسموحًا به، أو عدّل قائمة النماذج المسموح بها للمفتاح، أو قم بترقية خطتك.
404	لا	تحقّق من معرّف النموذج في صفحة النماذج.
413	لا	أرسل جسمًا أصغر، أو مرّر الملفات عبر URL بدلًا من base64.
429	لاحقًا	`rate_limited`: انتظر المدة المحددة في `Retry-After`. `daily_limit_reached`: انتظر يوم UTC التالي أو ارفع حد المفتاح. راجع حدود المعدّل.
502	نعم	أعِد المحاولة مع تراجع تدريجي (backoff)، أو أضف نماذج احتياطية.
503	نعم	أعِد المحاولة لاحقًا.

التعامل مع الأخطاء في الكود

import OpenAI from 'openai'

const client = new OpenAI({ baseURL: 'https://api14.com/api/v1', apiKey: process.env.API14_API_KEY })

try {
  await client.chat.completions.create({ model: 'openai/gpt-5-mini', messages: [{ role: 'user', content: 'Hi' }] })
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    console.error(err.status, err.code, err.message)
    if (err.code === 'insufficient_balance') {
      // prompt the user to add funds
    }
  } else {
    throw err
  }
}

from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api14.com/api/v1", api_key="sk-api14-...")

try:
    client.chat.completions.create(model="openai/gpt-5-mini", messages=[{"role": "user", "content": "Hi"}])
except APIStatusError as e:
    print(e.status_code, e.code, e.message)

الأخطاء التي تقع بعد بدء البث تصل داخل البث نفسه. راجع Streaming.