الأخطاء

تفشل كل نقطة نهاية بالطريقة نفسها: حالة HTTP وغلاف JSON واحد.

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}

لا تُحتسب أي رسوم على استدعاء يُرجع خطأً. يظل الطلب الذي يفشل بعد قبوله بحالة failed، ويحمل error: { "type", "code", "message" } في كائن الطلب، وتُسترد تكلفته تلقائيًا.

الأنواع#

الرموز#

invalid_request#

طلب عام غير صحيح البنية (400).

invalid_json#

النص ليس JSON صالحًا (400).

invalid_body#

النص JSON صالح لكنه ليس كائنًا؛ يجب أن يكون مدخل النموذج كائن JSON (400).

body_too_large#

النص أكبر من 16 MB (413). ارفع الملفات الكبيرة ومرّر عنوان URL الخاص بها بدلًا من ذلك (راجع الملفات).

invalid_parameter#

تحتوي معلمة استعلام على قيمة غير صحيحة، مثل limit خارج النطاق من 1 إلى 100، أو wait ليست رقمًا، أو status أو category غير معروفة، أو storage غير permanent / temporary (400). يحدّد param اسمها.

invalid_category#

يحدّد GET /openapi.json?category= فئة غير موجودة (400). يسردها GET https://api.doitong.com/v1/categories.

invalid_cursor#

لا ينتمي cursor الخاص باستدعاء قائمة إلى هذه القائمة (400). ابدأ مجددًا من دون مؤشر.

invalid_idempotency_key#

رأس Idempotency-Key فارغ أو أطول من 255 محرفًا (400).

invalid_arguments#

يحتوي استدعاء أداة MCP على وسيطة مفقودة أو غير صحيحة البنية (MCP فقط). يحدّد param اسم الوسيطة.

invalid_input#

لا يجتاز مدخل النموذج التحقق (422): معلمة غير معروفة (تقترح الرسالة أقرب اسم صالح)، أو معلمة مطلوبة مفقودة، أو نوع غير صحيح، أو قيمة خارج القائمة أو النطاق المسموح به، أو ورود الاسم الأساسي والاسم الأصلي معًا بقيم مختلفة. تمثل param أول معلمة مخالفة، وتسرد details جميع المعلمات. لا تُفرض أي رسوم.

unsupported_file#

يحتوي ملف على نوع لا نقبله (422)، مثل رفع بامتداد غير مدعوم، أو content_type لا يطابق الامتداد.

invalid_webhook_url#

webhook_url ليس عنوان URL عامًا يبدأ بـ https:// (422). تُرفض العناوين الخاصة والمحلية والعناوين العادية التي تبدأ بـ http://.

missing_api_key#

تحتاج نقطة النهاية إلى مفتاح API ولم يُرسل أي مفتاح (401).

invalid_api_key#

المفتاح غير معروف أو ملغى أو منتهي الصلاحية (401).

insufficient_scope#

يفتقر المفتاح إلى النطاق الذي يحتاجه هذا الاستدعاء (403)، مثل models:run للتشغيل، أو models:read لقراءة الطلبات والرصيد. راجع المصادقة.

account_disabled#

الحساب مغلق أو معلّق (403). لم تعد مفاتيحه تعمل.

not_found#

المسار غير موجود (404).

model_not_found#

لا يوجد نموذج عام بهذا المعرّف (404). اسرد النماذج باستخدام GET https://api.doitong.com/v1/models.

request_not_found#

لا يوجد في حسابك طلب بهذا المعرّف (404). لا تظهر طلبات الحسابات الأخرى مطلقًا.

insufficient_credits#

لا يغطي رصيد API في الحساب (أرصدة API، 1,000 رصيد API = ⁨‏1 $⁩ — وليس رصيد تطبيقات Doitong) تكلفة هذا الاستدعاء (402). تُرسل الاستجابة قبل فرض أي رسوم. يحتوي الخطأ على top_up_url؛ أضف المال من https://doitong.com/developers/dashboard#balance ثم أعد المحاولة.

{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
             "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }

budget_exceeded#

سيتجاوز الاستدعاء ميزانية مفتاح API نفسه بأرصدة API (402). يحدّد مالك المفتاح الميزانية؛ ولن تفيد إعادة المحاولة حتى يرفعها.

conflict#

يتعارض الاستدعاء مع الحالة الحالية للمورد (409).

idempotency_mismatch#

استُخدم Idempotency-Key من قبل مع نص مختلف (409). استخدم مفتاحًا جديدًا لعملية جديدة.

idempotency_in_progress#

يجري الآن إنشاء طلب باستخدام Idempotency-Key نفسه (409). أعد المحاولة بعد لحظة للحصول عليه.

request_active#

لا يزال الطلب queued أو running، لذا لا توجد ملفات لحذفها بعد (409). احذفها بعد انتهائه.

not_cancelable#

الطلب succeeded أو failed بالفعل، ولا يمكن إلغاؤه (409).

rate_limited#

أجرى المفتاح عددًا كبيرًا من الطلبات في النافذة الحالية (429). راجع رأسي X-RateLimit-* وRetry-After.

too_many_inflight#

لدى الحساب 10 طلبات queued أو running بالفعل (429). ابدأ الطلب التالي عند انتهاء أحدها.

upstream_error#

رفض نظام النموذج الخلفي الطلب أو فشل فيه (502 عند التشغيل، أو failed بهذا الرمز في الطلب). تُسترد أرصدة API. إذا رفض النظام الخلفي المدخل نفسه، يُرجع الاستدعاء 422 invalid_input مع رسالته بدلًا من ذلك.

upstream_lost#

لم يعد نظام النموذج الخلفي يعرف الطلب، لذا لن تصل أي نتيجة مطلقًا. ينتهي بحالة failed مع هذا الرمز (النوع upstream_error) وتُسترد تكلفته. شغّله مجددًا.

timeout#

استمر الطلب مدة أطول من حده (15 دقيقة للصور، و60 للفيديو، و30 لغير ذلك) وأُوقف. ينتهي بحالة failed مع هذا الرمز وتُسترد تكلفته.

service_unavailable#

توقف API مؤقتًا، أو توقفت تبعية مثل رفع الملفات (503). أعد المحاولة لاحقًا.

internal_error#

حدث خلل من جانبنا (500). أعد المحاولة؛ وإذا استمر، تواصل مع الدعم.

charge_failed#

تعذّر فرض الرسوم على الحساب بسبب مشكلة داخلية (500). يُعلّم الطلب بحالة failed؛ ولم يُخصم شيء. أعد المحاولة.

pricing_unavailable#

لم يُضبط سعر النموذج، لذا لا يمكن عرض سعره أو تشغيله الآن (500).