رموز الأخطاء واستكشافها

مرجع كامل لاستجابات أخطاء واجهة الوكيل البرمجية وكيفية معالجتها.

رموز حالة HTTP

Status	المعنى	الإجراء
200	نجاح	معالجة بيانات الاستجابة
400	طلب غير صالح	تحقق من تنسيق الطلب والمعلمات
401	غير مصرح	تحقق من صلاحية مفتاح الواجهة وإدراجه
404	غير موجود	تحقق من وجود معرّف المورد
429	حد المعدل	انتظر قبل إعادة المحاولة
500	خطأ خادم	أعد المحاولة لاحقاً أو اتصل بالدعم

أخطاء التسجيل

صيغة البريد غير صالحة

الحالة: 400

الاستجابة:

{
  "error": "Invalid email format"
}

السبب: البريد لا يطابق نمط البريد الصالح

الحل: تحقق من صيغة البريد قبل الإرسال

---

بريد مؤقت

الحالة: 400

الاستجابة:

{
  "error": "Disposable email addresses are not allowed"
}

السبب: البريد من نطاق بريد مؤقت معروف

الحل: استخدم عنوان بريد دائم

---

تجاوز حد المعدل (لكل بريد)

الحالة: 429

الاستجابة:

{
  "error": "Rate limit exceeded: max 1 request per email per 24 hours"
}

السبب: نفس البريد استُخدم في آخر 24 ساعة

الحل: انتظر 24 ساعة أو استخدم بريداً مختلفاً

---

تجاوز حد المعدل (لكل IP)

الحالة: 429

الاستجابة:

{
  "error": "Rate limit exceeded: too many requests from this IP"
}

السبب: طلبات كثيرة من نفس عنوان IP

الحل: انتظر قبل إعادة المحاولة

---

تجاوز حد المعدل (عالمي)

الحالة: 429

الاستجابة:

{
  "error": "Service temporarily unavailable, please try again later"
}

السبب: تم الوصول للحد العام للنظام

الحل: أعد المحاولة بعد تأخير

---

حقل مطلوب ناقص

الحالة: 400

الاستجابة:

{
  "error": "operator_email is required"
}

السبب: حقل مطلوب ناقص في الطلب

الحل: أدرج كل الحقول المطلوبة

أخطاء التحقق من الحالة

التسجيل غير موجود

الحالة: 404

الاستجابة:

{
  "error": "Registration not found"
}

السبب: registration_id غير صالح أو غير موجود

الحل: تحقق من صحة registration_id

---

انتهت صلاحية الرمز

الحالة: 200 (لكن الحالة "expired")

الاستجابة:

{
  "status": "expired",
  "message": "Registration token has expired"
}

السبب: المشغّل لم يوافق خلال 24 ساعة

الحل: أنشئ تسجيلاً جديداً

---

رُفض التسجيل

الحالة: 200 (لكن الحالة "rejected")

الاستجابة:

{
  "status": "rejected",
  "message": "Registration was declined by operator"
}

السبب: المشغّل نقر "Decline"

الحل: تواصل مع المشغّل أو جرّب بريداً مختلفاً

أخطاء واجهة النموذج

غير مصرح (مفتاح واجهة ناقص)

الحالة: 401

الاستجابة:

{
  "error": "Unauthorized"
}

السبب: رأس Authorization ناقص أو غير صالح

الحل: أدرج رأس Authorization: Bearer sr_live_xxx

---

مفتاح واجهة غير صالح

الحالة: 401

الاستجابة:

{
  "error": "Unauthorized"
}

السبب: مفتاح الواجهة غير موجود أو منتهي أو غير نشط

الحل:

• تحقق من صحة المفتاح
• تحقق من عدم انتهاء المفتاح
• تحقق من عدم إلغاء المفتاح

---

النموذج غير موجود

الحالة: 404

الاستجابة:

{
  "error": "النموذج not found"
}

السبب: المستخدم ليس لديه نموذج (لا يفترض أن يحدث، لكن ممكن)

الحل: اتصل بالدعم

---

لا حقول صالحة للتحديث

الحالة: 400

الاستجابة:

{
  "error": "No valid fields to update"
}

السبب: كل الحقول في طلب التحديث محمية أو غير صالحة

الحل: أدرج حقل واحد صالح على الأقل غير محمي

أخطاء التحقق

رمز غير صالح

الحالة: 404

الاستجابة:

{
  "error": "Invalid or expired token"
}

السبب: الرمز غير موجود أو تالف

الحل: استخدم الرمز الصحيح من البريد

---

انتهت صلاحية الرمز

الحالة: 400

الاستجابة:

{
  "error": "Token has expired"
}

السبب: الرمز أقدم من 24 ساعة

الحل: اطلب تسجيلاً جديداً

---

مُعالَج مسبقاً

الحالة: 400

الاستجابة:

{
  "error": "Registration already processed",
  "status": "approved"
}

السبب: الرمز استُخدم مسبقاً

الحل: تحقق من نقطة الحالة للحالة الحالية

---

فشل تحقق Turnstile

الحالة: 400

الاستجابة:

{
  "error": "Verification failed. Please try again."
}

السبب: فشل تحدي Turnstile أو كان ناقصاً

الحل: أكمل تحدي Turnstile في صفحة الموافقة

---

كلمة المرور قصيرة جداً

الحالة: 400

الاستجابة:

{
  "error": "كلمة المرور is required and must be at least 8 characters"
}

السبب: كلمة المرور أقل من 8 أحرف

الحل: استخدم كلمة مرور من 8 أحرف أو أكثر

أفضل ممارسات معالجة الأخطاء

منطق إعادة المحاولة

للأخطاء العابرة (429، 500)، نفّذ backoff أسي:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status === 500) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

التحقق قبل الإرسال

تحقق دائماً من المدخلات قبل استدعاءات الواجهة:

function validateالبريد الإلكتروني(email) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

if (!validateالبريد الإلكتروني(operatorالبريد الإلكتروني)) {
  throw new Error("Invalid email format");
}

معالجة كل قيم الحالة

عند استعلام الحالة، عالج كل القيم الممكنة:

const status = response.status;

switch (status) {
  case "pending_verification":
    // Continue polling
    break;
  case "approved":
    // Use API key and form URL
    break;
  case "rejected":
    // Registration failed
    break;
  case "expired":
    // Token expired, create new registration
    break;
  default:
    // Unknown status
    break;
}

مشاكل شائعة

مفتاح الواجهة لا يعمل

الأعراض: أخطاء 401 Unauthorized

قائمة التحقق:

• ✅ تنسيق المفتاح: sr_live_ + 64 حرف hex
• ✅ رأس المصادقة: Bearer sr_live_xxx
• ✅ المفتاح لم ينتهِ (90 يوماً افتراضياً)
• ✅ المفتاح نشط (لم يُلغَ)

التسجيل عالق في الانتظار

الأعراض: الحالة تبقى "pending_verification" دون نهاية

أسباب محتملة:

• المشغّل لم يتحقق من البريد
• البريد ذهب للسبام
• المشغّل رفض لكن الحالة لم تُحدَّث بعد

الحل: انتظر وقتاً معقولاً، ثم أنشئ تسجيلاً جديداً إن لزم

تحديثات النموذج لا تُطبَّق

الأعراض: طلب PUT ينجح لكن النموذج لا يتغير

تحقق:

• ✅ الحقول في القائمة المسموحة (ليست محمية)
• ✅ تنسيق اللون صحيح (6 أحرف hex، بدون #)
• ✅ قيم الحقول تلبي القيود (مثلاً طول العنوان)

مواضيع ذات صلة

• Registration Flow
• النموذج Customization
• Getting Started