الأخطاء وحدود المعدل

تعامل مع الأخطاء كحالات منتج صريحة. لا تخفها خلف retries صامتة.

حالات شائعة

الحالة	المعنى	ماذا تفعل
`400`	شكل الطلب غير صالح أو mode غير مدعوم أو scope خاطئ أو schema لا يطابق.	راجع `model` و`mode` و`input` و`params` و`scope`.
`401`	المصادقة مفقودة أو غير صالحة.	أرسل `X-API-Key` لطلبات الخادم أو bearer token صالح للتدفقات المسجلة الدخول.
`402`	حالة الدفع أو المحفظة تمنع التنفيذ.	راجع الفوترة ورصيد المحفظة لمساحة العمل النشطة.
`403`	الاعتماد صالح لكن لا يملك الصلاحية.	تأكد من عضوية مساحة العمل وصلاحيات API key.
`404`	النموذج أو المورد غير موجود.	تحقق من model slug وأن النموذج منشور.
`409`	تعارض في هوية النموذج أو الحالة.	راجع slug ولا تعيد المحاولة إلا بعد حل التعارض.
`429`	تم تجاوز حد المعدل.	احترم `Retry-After` وقلل حجم الطلبات.
`502`	فشل في control plane أو runtime.	أعد المحاولة لاحقاً فقط إذا كانت العملية آمنة وواضحة للمستخدم.

ترويسات حدود المعدل

قد تحتوي الاستجابات على:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1710000000
Retry-After: 60

إذا حصلت على 429، انتظر مدة Retry-After قبل إرسال طلب آخر.

أخطاء schema

أخطاء schema تعني غالباً أن طلب API لا يطابق عقد النموذج. افتح النموذج في Playground، شغّل نفس العملية، وقارن شكل المدخلات الناتج مع payload التكامل.

أخطاء الرصيد

أخطاء الرصيد تعني أن مساحة العمل النشطة لا تستطيع دفع تكلفة الاستخدام. افتح Billing وراجع حالة المحفظة وطرق الدفع وملخص الاستخدام، ثم أعد المحاولة فقط بعد أن تكون مساحة العمل نشطة وممولة.