توثيق الـ API

الأخطاء

شكل الخطأ الموحّد، ورموز الأخطاء الثابتة، ومتى تعيد المحاولة.

كل خطأ يرجع بحالة HTTP مناسبة وبنفس الشكل. اعتمد في برمجتك على code فقط: الرسائل قد تتغير صياغتها.

شكل الخطأ

{
  "error": {
    "code": "validation_failed",
    "message": "The request is invalid. Check the parameters and try again.",
    "message_ar": "الطلب غير صالح. تحقق من المعطيات وأعد المحاولة.",
    "detail": "invalid phone number"
  }
}

حقول الخطأ

error.codestringپێویستە
رمز ثابت من الجدول أدناه.
error.messagestringپێویستە
وصف بالإنگليزية يمكن عرضه للمستخدم.
error.message_arstringپێویستە
نفس الوصف بالعربية.
error.detailstring
اختياري: تلميح تقني بالإنگليزية، مثل اسم الحقل الخاطئ. للتشخيص فقط.

رموز الأخطاء

HTTP	code	المعنى
`400`	`validation_failed`	معطيات غير صالحة: رقم، JSON، حقل غير معروف، أو `Idempotency-Key` غير صالح
`401`	`unauthenticated`	مفتاح API مفقود أو غير صالح أو ملغى
`402`	`insufficient_balance`	الرصيد لا يكفي لأول قناة. لم يُرسل شيء
`402`	`spend_cap_reached`	تم بلوغ حد الصرف الشهري للمشروع
`403`	`forbidden`	عنوان IP الخادم خارج القائمة المسموحة
`403`	`test_number_required`	مفتاح الاختبار يرسل لأرقام الاختبار المسجلة فقط
`404`	`not_found`	غير موجود، أو يعود لمشروع آخر أو لوضع آخر (test/live)
`409`	`idempotency_conflict`	المفتاح استُخدم مع طلب مختلف، أو الطلب الأول ما زال قيد التنفيذ
`429`	`rate_limited`	تجاوز حد الطلبات لنفس الرقم أو الـ IP. يأتي مع `Retry-After: 60`
`500`	`internal_error`	خطأ من جهتنا
`502`	`delivery_failed`	فشلت كل القنوات وأُعيد كامل المبلغ
`503`	`no_channel_available`	لا قناة مفعّلة ومسعّرة لهذا الرقم

متى تعيد المحاولة

429: انتظر المدة في Retry-After (بالثواني) ثم أعد.
500 أو انقطاع الشبكة: أعد بنفس Idempotency-Key، فلن يُرسل الرمز مرتين. انظر Idempotency.
502 delivery_failed و503: لا فائدة من الإعادة الفورية. اعرض للمستخدم خياراً آخر أو أعد لاحقاً.
400 و401 و402 و403 و404: أصلح الطلب أو الإعدادات أولاً.