التوثيق/معالجة الأخطاء

معالجة الأخطاء

تتبع جميع أخطاء الواجهة البرمجية تنسيقًا موحّدًا. إليكم كيفية التعامل معها بسلاسة.

عرض Markdown OpenAPI JSON

تنسيق استجابة الخطأ

عند حدوث خطأ، تُرجع الواجهة البرمجية كائن JSON بالبنية التالية:

json
{
  "error": "Validation Error",
  "message": "The email field is required.",
  "status_code": 422
}

رموز الأخطاء

رمز الحالةالخطأالسبب والحل
400 طلب غير صالح JSON غير سليم أو حقول مطلوبة مفقودة. راجعوا نص الطلب.
401 غير مصرّح مفتاح API مفقود أو غير صالح. راجعوا ترويسة Authorization .
402 الدفع مطلوب الأرصدة غير كافية. اشتروا مزيدًا من الأرصدة أو انتظروا إعادة تعيين الحد اليومي.
422 خطأ في التحقق من صحة البيانات صيغة عنوان البريد الإلكتروني غير صالحة. راجعوا القيمة التي ترسلونها.
429 طلبات كثيرة جدًا تم تجاوز حد المعدل. راجعوا ترويسة Retry-After وانتظروا.
500 خطأ داخلي في الخادم حدث خطأ ما من جهتنا. حاولوا مجددًا بعد بضع ثوانٍ. تواصلوا مع الدعم إذا استمر الفشل.

401 Unauthorized

json
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "status_code": 401
}

الحل: تأكدوا من أن ترويسة Authorization منسّقة بشكل صحيح على النحو Bearer YOUR_API_KEY. تحققوا من مفتاحكم في لوحة التحكم.

422 Validation Error

json
{
  "error": "Validation Error",
  "message": "The email field must be a valid email address.",
  "status_code": 422
}

الحل: تأكدوا من أن قيمة البريد الإلكتروني بصيغة صالحة (مثل user@example.com). نظّفوا المدخلات قبل الإرسال.

429 Too Many Requests

json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please slow down.",
  "status_code": 429,
  "retry_after": 15
}

الحل: انتظروا عدد الثواني المحدد في retry_after قبل إعادة المحاولة. راجعوا حدود المعدل ←

قائمة التحقق لاستكشاف الأخطاء