رموز الأخطاء

عند الفشل، تحقق من رمز حالة HTTP وحقل message.

جسم الخطأ

أخطاء الأعمال تُرجع دائماً رمزاً (code) قابلاً للقراءة آلياً لتتمكن من التفرع برمجياً. أما المعاملات غير الصالحة (التحقق) والمسارات غير الموجودة فتُرجع بنية Laravel القياسية: { “message”: ”…”, “errors”: { … } }. تحقق من المدخلات قبل الإرسال.

{
  "code": "insufficient_balance",
  "message": "Insufficient balance. Please top up and try again."
}

خطأ

code	HTTP	الوصف
unauthorized	401	مفتاح API مفقود أو غير صالح أو معطّل.
account_banned	403	الحساب موقوف. تواصل مع الدعم.
invalid_realtime_request	400	طلب فوري غير صالح (مثل رقم هاتف بدون بادئة دولية + عند ترك country فارغاً).
idempotency_key_required	400	الطلبات الفورية تتطلب الترويسة Idempotency-Key.
invalid_idempotency_key	422	معرّف Idempotency-Key غير صالح: من 1 إلى 128 حرفاً من الحروف والأرقام و . _ : -
idempotency_conflict	409	استُخدم نفس المعرّف مع محتوى طلب مختلف.
request_in_progress	409	طلب فوري مطابق قيد المعالجة حالياً. أعد المحاولة بعد قليل (Retry-After: 1).
empty_input	422	الملف المرفوع لا يحتوي على صفوف قابلة للاستخدام.
product_not_found	422	المعرّف الفريد للمنتج غير موجود أو غير مفعّل.
product_mode_not_supported	422	نقطة النهاية هذه لا تقبل هذا النمط من المنتجات (منتجات الفحص الفوري لا تُرسل إلى نقاط المعالجة الجماهيرية).
invalid_country	422	المنتج لا يدعم الدولة المرسلة.
too_few_numbers	422	الإرسال أقل من الحد الأدنى للمنتج.
too_many_numbers	422	الإرسال يتجاوز الحد الأقصى للمنصة.
insufficient_balance	402	الرصيد غير كافٍ. اشحن ثم أعد المحاولة.
realtime_disabled	403	الفحص الفوري غير مفعّل لهذا الحساب.
realtime_rate_limited	429	تجاوزت حد معدل الطلبات الفورية. التزم بـ retry_after.
product_pricing_unavailable	503	لم يتم ضبط أسعار هذا المنتج بعد. تواصل مع الدعم.
detection_capacity_unavailable	503	لا توجد سعة فحص متاحة حالياً. أعد المحاولة لاحقاً.
realtime_route_unavailable	503	لا يوجد مسار فوري متاح. أعد المحاولة لاحقاً.
realtime_fact_cache_unavailable	503	إحدى خدمات الفحص الفوري غير متاحة مؤقتاً. أعد المحاولة لاحقاً.
realtime_rate_limiter_unavailable	503	محدد المعدل غير متاح مؤقتاً. أعد المحاولة لاحقاً.
internal_error	500	خطأ داخلي في الخادم. إعادة المحاولة بنفس المعرّف آمنة.

أعطال بلا رمز

ليست كل الأعطال تحمل code. تُبلغ نقاط نهاية المهمة عن أربع حالات بحالة HTTP وmessage فقط، لأن تلك الأعطال تحدث قبل الوصول إلى مسار أخطاء الأعمال:

HTTP	الحالة	الجسم
404	قيمة task_id غير موجودة أو تنتمي إلى حساب آخر	message فقط
404	GET /v1/tasks/{token}/download — ملف النتائج غير متاح أو منتهي الصلاحية أو لم يعد قابلًا للتنزيل	message فقط
422	GET /v1/tasks/{token}/result — النتيجة غير جاهزة: المهمة لم تكتمل، أو لم يُنشأ الملف، أو انتهت صلاحيته	message فقط
422	فشل التحقق من معاملات الطلب	{ "message": …, "errors": { … } }

اعتمد على حالة HTTP في هذه الحالات. أما message فهو للسجلات ولمن يقرأ الحادث، لا لمنطق التحكم.

أرسل Accept: application/json

تكون هذه الأجسام بصيغة JSON عندما يطلب الطلب ذلك. أما العميل الذي لا يرسل ترويسة Accept فقد يتلقى صفحة خطأ HTML بدلًا منها، وهو أمر عسير التشخيص في الثالثة فجرًا. جميع الأمثلة في هذا التوثيق ترسل JSON.

إعادة المحاولة

تتوقف الاستجابة الصحيحة لأي فشل على ما إذا كان تكرار الطلب قد يُنتج نتيجة مختلفة.

إجراء مطلوب أولًا

إعادة المحاولة دون تغيير تكرّر الفشل نفسه.

unauthorized, account_banned, invalid_realtime_request, idempotency_key_required, invalid_idempotency_key, idempotency_conflict, empty_input, product_not_found, product_mode_not_supported, invalid_country, too_few_numbers, too_many_numbers, insufficient_balance, realtime_disabled, product_pricing_unavailable

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

عابر — يُفترض أن ينجح الطلب نفسه لاحقًا.

realtime_rate_limited, request_in_progress, detection_capacity_unavailable, realtime_route_unavailable, realtime_fact_cache_unavailable, realtime_rate_limiter_unavailable

النتيجة غير محسومة

قد يكون الطلب قد نُفّذ أو لم يُنفّذ. أعد المحاولة بالمفتاح نفسه.

internal_error