مرجع رموز أخطاء CaptchaAI: الدليل الكامل والإصلاحات

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

تحتوي واجهة برمجة تطبيقات CaptchaAI على نقطتي نهاية:

• in.php — إرسال مهمة CAPTCHA (تحدث أخطاء في وقت الإرسال)
• res.php — استطلاع للنتيجة (تحدث أخطاء أثناء استرجاع النتائج)

عندما تقوم بتضمين json=1 في طلبك، تعود الأخطاء بتنسيق JSON:

{"status": 0, "request": "ERROR_CODE_HERE"}

بدون json=1، تعود الأخطاء كنص عادي: ERROR_CODE_HERE

قواعد معالجة الأخطاء السريعة

قبل المرجع الكامل، إليك القواعد الثلاث التي تعالج 90% من الحالات:

إرسال الأخطاء (in.php)

تحدث هذه الأخطاء عند إرسال مهمة CAPTCHA جديدة.

ERROR_WRONG_USER_KEY

السبب: تحتوي المعلمة key على تنسيق غير صحيح. تتكون مفاتيح CaptchaAI API من 32 حرفًا.

الإصلاح:

1. تأكد من أن مفتاحك يتكون من 32 حرفًا بالضبط.
2. تأكد من عدم وجود مسافات إضافية أو فواصل أسطر.
3. انسخ المفتاح مباشرة منcaptchaai.com/api.php.

{
  "key": "abc123... "
}

{
  "key": "abc12345678901234567890123456789a"
}

ERROR_KEY_DOES_NOT_EXIST

السبب: مفتاح API لا يتطابق مع أي حساب في النظام.

الإصلاح:

1. تسجيل الدخولcaptchaai.comوانسخ المفتاح من لوحة التحكم الخاصة بك.
2. تأكد من أنك تستخدم مفتاح الحساب الصحيح.
3. إذا قمت بإنشاء الحساب مؤخرًا، فانتظر بضع دقائق حتى يتم تنشيط المفتاح.

ERROR_ZERO_BALANCE

السبب: لا يحتوي حسابك على رصيد كافٍ. ملاحظة: قد يعني هذا أيضًا أن جميع مسارات التنفيذ المتزامنة (threads) مشغولة.

الإصلاح:

1. انتظر حتى تكتمل المهام قيد التشغيل (سيتم تحرير threads).
2. قم بترقية خطتك للحصول على مزيد من التنفيذ المتوازي.
3. افحص رصيد حسابك عبر captchaai.com/api.php.

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

ERROR_PAGEURL

السبب: معلمة pageurl مفقودة أو فارغة. هذه المعلمة مطلوبة لاختبارات CAPTCHA المستندة إلى الرمز المميز (reCAPTCHA، Cloudflare Turnstile، GeeTest، وما إلى ذلك).

الإصلاح: أضف عنوان URL الكامل للصفحة التي يتم تحميل اختبار CAPTCHA فيها، بما في ذلك البروتوكول:

{
  "pageurl": ""
}

{
  "pageurl": "https://example.com/login"
}

ERROR_WRONG_GOOGLEKEY / ERROR_GOOGLEKEY

السبب: معلمة googlekey (مفتاح الموقع) فارغة أو مشوهة أو مفقودة.

الإصلاح:

1. أعد استخراج مفتاح الموقع من سمة data-sitekey للصفحة المستهدفة أو معلمة عنوان URL لرابط reCAPTCHA k.
2. تأكد من أن القيمة ليست فارغة أو مقطوعة.

{
  "googlekey": ""
}

{
  "googlekey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
}

ERROR_BAD_TOKEN_OR_PAGEURL

السبب: مجموعة googlekey (مفتاح الموقع) وpageurl غير صالحة. لم يتم تسجيل مفتاح الموقع لعنوان URL للصفحة المحددة.

الأسباب الشائعة:

• يتم تحميل عنصر واجهة المستخدم reCAPTCHA داخل إطار iframe على نطاق فرعي مختلف. أنت تستخدم عنوان URL للصفحة الأصلية بدلاً من عنوان URL لـ iframe.
• ينتمي مفتاح الموقع إلى صفحة أو مجال مختلف.
• تم استخراج مفتاح الموقع من بيئة التطوير/staging.

الإصلاح:

1. إذا كان reCAPTCHA موجودًا في إطار iframe، فاستخدم عنوان URL src الخاص بـ iframe باعتباره pageurl.
2. تحقق من مفتاح الموقع من صفحة الإنتاج المباشر.
3. اختبر كلا القيمتين عن طريق تحميل عنوان URL لرابط reCAPTCHA يدويًا: https://www.google.com/recaptcha/api2/anchor?k=YOUR_SITEKEY

ERROR_TOO_BIG_CAPTCHA_FILESIZE

السبب: الصورة التي تم تحميلها تتجاوز الحد الأقصى للحجم المسموح به.

الإصلاح: ضغط الصورة أو تغيير حجمها قبل إرسالها. استخدم JPEG للصور، وPNG لالتقاط لقطات الشاشة.

ERROR_ZERO_CAPTCHA_FILESIZE

السبب: ملف الصورة صغير جدًا (أقل من 100 بايت)، مما يشير إلى تحميل فارغ أو تالف.

الإصلاح: تأكد من أنك ترسل بيانات صورة فعلية، وليس ملفًا فارغًا أو سلسلة Base64 معطلة.

ERROR_WRONG_FILE_EXTENSION

السبب: الملف الذي تم تحميله له امتداد غير مدعوم. المدعومة: jpg، jpeg، png، gif.

الإصلاح: تحويل الصورة إلى تنسيق مدعوم قبل التحميل.

ERROR_IMAGE_TYPE_NOT_SUPPORTED

السبب: لا يمكن للخادم تحديد نوع الصورة من محتوى الملف.

الإصلاح: التحويل إلى تنسيق قياسي (PNG أو JPEG) والتأكد من عدم تلف الملف.

ERROR_UPLOAD

السبب: تعذر على الخادم قراءة الملف الذي تم تحميله أو حمولة Base64.

الإصلاح:

1. لتحميل الملفات: تحقق من ترميز بيانات النموذج متعدد الأجزاء.
2. بالنسبة إلى base64: تحقق من اكتمال سلسلة base64 وترميزها بشكل صحيح.
3. اختبر باستخدام صورة معروفة جيدة لاستبعاد تلف الملف.

ERROR_BAD_PROXY

السبب: الوكيل الذي قدمته لا يمكن الوصول إليه أو تم تصنيفه على أنه سيئ من قبل النظام.

الإصلاح:

1. اختبر الوكيل بشكل مستقل — هل يمكنه الاتصال بالموقع المستهدف؟
2. حاول وكيلا مختلفا.
3. تحقق من التنسيق: login:password@IP:PORT أو IP:PORT لوكلاء IP المصادق عليهم.

يجب تمكين استخدام الوكيل في حسابك. اتصل بدعم CaptchaAI إذا لم تقم بذلك.

ERROR_BAD_PARAMETERS

السبب: المعلمات المطلوبة مفقودة أو تحتوي على أنواع بيانات خاطئة.

الإصلاح: تحقق من وثائق واجهة برمجة التطبيقات (API) الخاصة بنوع اختبار CAPTCHA المحدد الذي تقوم بحله وتحقق من وجود جميع المعلمات المطلوبة:

IP_BANNED

السبب: تم حظر عنوان IP الخاص بك مؤقتًا بعد محاولات المصادقة الفاشلة المتكررة.

الإصلاح: انتظر لمدة 5 دقائق تقريبًا، ثم أعد المحاولة باستخدام بيانات الاعتماد الصحيحة. لا تستمر في إرسال الطلبات باستخدام مفاتيح API خاطئة.

ERROR_SERVER_ERROR / ERROR_INTERNAL_SERVER_ERROR

السبب: حدث خطأ عابر من جانب الخادم.

الإصلاح: انتظر 10 ثوانٍ ثم أعد المحاولة. استخدم التراجع الأسي للفشل المتكرر:

import time

retry_delay = 10
for attempt in range(5):
    response = submit_captcha()
    if response.get("status") == 1:
        break
    time.sleep(retry_delay)
    retry_delay *= 2  # 10s, 20s, 40s, 80s, 160s

أخطاء استرجاع النتائج (res.php)

تحدث هذه الأخطاء عند التحقق من حالة المهمة المرسلة.

CAPCHA_NOT_READY

هذا ليس خطأ. إنه يعني أن الحل لا يزال قيد التقدم.

الإجراء: انتظر 5 ثوانٍ وقم بالاستطلاع مرة أخرى.

if result.get("request") == "CAPCHA_NOT_READY":
    time.sleep(5)
    continue  # poll again

دليل التوقيت: | نوع التحقق | أول استطلاع بعد | الفاصل الزمني للاستقصاء | |---|---|---| | reCAPTCHA v2/v3/Enterprise | 15 ثانية | 5 ثواني | | Cloudflare Turnstile | 15 ثانية | 5 ثواني | | Cloudflare Challenge | 20 ثانية | 5 ثواني | | GeeTest v3 | 15 ثانية | 5 ثواني | | عادي/image CAPTCHA | 5 ثواني | 5 ثواني |

ERROR_CAPTCHA_UNSOLVABLE

السبب: لم يتمكن CaptchaAI من حل اختبار CAPTCHA بعد عدة محاولات.

الأسباب الشائعة:

1. نوع CAPTCHA غير مدعوم أو المعلمات خاطئة.
2. التحدي تالف أو منتهية الصلاحية.
3. بالنسبة للحلول المستندة إلى الوكيل: الوكيل بطيء جدًا أو لا يمكن الوصول إليه.
4. قام الموقع بتغيير تطبيق CAPTCHA الخاص به.

الإصلاح:

1. تحقق من صحة المعلمات (مفتاح الموقع، عنوان URL للصفحة، الطريقة).
2. إعادة الإرسال مع طلب جديد.
3. في حالة استخدام وكيل، حاول استخدام وكيل مختلف.
4. إذا استمر الخطأ، فربما يكون الموقع قد تغير — أعد استخراج مفتاح الموقع وعنوان URL للصفحة.

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

ERROR_WRONG_ID_FORMAT

السبب: يجب أن يكون معرف captcha رقميًا فقط.

الإصلاح: تأكد من أنك ترسل المعرف الدقيق الذي تم إرجاعه بواسطة in.php (أرقام فقط، بدون أحرف إضافية).

ERROR_WRONG_CAPTCHA_ID

السبب: معرف المهمة غير موجود أو انتهت صلاحيته.

الإصلاح:

1. تأكد من قيامك بالاقتراع باستخدام المعرف الذي تم إرجاعه بواسطة إرسالك.
2. قد تنتهي صلاحية معرفات المهام بعد فترات طويلة — أعد الإرسال إذا كانت المهمة قديمة جدًا.

ERROR_EMPTY_ACTION

السبب: معلمة action مفقودة أو فارغة في طلب الاستقصاء.

الإصلاح: إضافة action=get إلى طلب res.php الخاص بك:

params = {
    "key": api_key,
    "action": "get",  # Required
    "id": captcha_id,
    "json": 1,
}

ERROR_PROXY_CONNECTION_FAILED

السبب: تعذر على الحل الاتصال بالموقع المستهدف من خلال الوكيل الخاص بك.

الإصلاح:

1. قد يكون الوكيل معطلاً مؤقتًا - جرّب خادمًا مختلفًا.
2. قد يكون الموقع المستهدف يحظر عنوان IP للوكيل.
3. تأكد من أن الوكيل يمكنه الوصول بالفعل إلى الموقع المستهدف.

ERROR_WRONG_USER_KEY / ERROR_KEY_DOES_NOT_EXIST

يمكن أن تظهر هذه أيضًا على res.php - نفس السبب والإصلاح مثل أخطاء الإرسال أعلاه.

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

انسخ هذا النمط لمعالجة الأخطاء بشكل فعال بأي لغة:

بايثون

import time
import requests

API_KEY = "YOUR_API_KEY"
SUBMIT_URL = "https://ocr.captchaai.com/in.php"
RESULT_URL = "https://ocr.captchaai.com/res.php"

# Errors that should not be retried (fix the request first)
NO_RETRY_ERRORS = {
    "ERROR_WRONG_USER_KEY",
    "ERROR_KEY_DOES_NOT_EXIST",
    "ERROR_PAGEURL",
    "ERROR_WRONG_GOOGLEKEY",
    "ERROR_GOOGLEKEY",
    "ERROR_BAD_TOKEN_OR_PAGEURL",
    "ERROR_BAD_PARAMETERS",
    "ERROR_WRONG_FILE_EXTENSION",
    "ERROR_IMAGE_TYPE_NOT_SUPPORTED",
    "IP_BANNED",
}

# Errors that can be retried
RETRY_ERRORS = {
    "ERROR_ZERO_BALANCE",
    "ERROR_SERVER_ERROR",
    "ERROR_INTERNAL_SERVER_ERROR",
    "ERROR_UPLOAD",
}


def solve_captcha(submit_data, max_retries=3, max_polls=60):
    """Submit and solve a CAPTCHA with full error handling."""

    # Submit with retry logic
    for attempt in range(max_retries):
        resp = requests.post(SUBMIT_URL, data={**submit_data, "json": 1}, timeout=30)
        resp.raise_for_status()
        data = resp.json()

        if data.get("status") == 1:
            captcha_id = data["request"]
            break

        error = data.get("request", "UNKNOWN")

        if error in NO_RETRY_ERRORS:
            raise ValueError(f"Fatal error (fix request): {error}")

        if error in RETRY_ERRORS and attempt < max_retries - 1:
            time.sleep(10 * (2 ** attempt))
            continue

        raise RuntimeError(f"Submit failed: {error}")
    else:
        raise RuntimeError("Submit failed after max retries")

    # Poll for result
    time.sleep(15)

    for _ in range(max_polls):
        resp = requests.get(
            RESULT_URL,
            params={"key": API_KEY, "action": "get", "id": captcha_id, "json": 1},
            timeout=30,
        )
        data = resp.json()

        if data.get("request") == "CAPCHA_NOT_READY":
            time.sleep(5)
            continue

        if data.get("status") == 1:
            return data["request"]

        error = data.get("request", "UNKNOWN")
        if error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable — resubmit with fresh parameters")

        raise RuntimeError(f"Poll error: {error}")

    raise TimeoutError("Solve timed out")

Node.js

const NO_RETRY_ERRORS = new Set([
  "ERROR_WRONG_USER_KEY",
  "ERROR_KEY_DOES_NOT_EXIST",
  "ERROR_PAGEURL",
  "ERROR_WRONG_GOOGLEKEY",
  "ERROR_BAD_TOKEN_OR_PAGEURL",
  "ERROR_BAD_PARAMETERS",
  "IP_BANNED",
]);

async function solveCaptcha(submitData, maxRetries = 3, maxPolls = 60) {
  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

  // Submit with retry
  let captchaId;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const resp = await fetch("https://ocr.captchaai.com/in.php", {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({ ...submitData, json: "1" }),
    });
    const data = await resp.json();

    if (data.status === 1) {
      captchaId = data.request;
      break;
    }

    if (NO_RETRY_ERRORS.has(data.request)) {
      throw new Error(`Fatal error: ${data.request}`);
    }

    if (attempt < maxRetries - 1) {
      await sleep(10_000 * 2 ** attempt);
      continue;
    }

    throw new Error(`Submit failed: ${data.request}`);
  }

  // Poll for result
  await sleep(15_000);

  for (let i = 0; i < maxPolls; i++) {
    const resp = await fetch(
      `https://ocr.captchaai.com/res.php?${new URLSearchParams({
        key: submitData.key,
        action: "get",
        id: captchaId,
        json: "1",
      })}`
    );
    const data = await resp.json();

    if (data.request === "CAPCHA_NOT_READY") {
      await sleep(5_000);
      continue;
    }

    if (data.status === 1) return data.request;

    throw new Error(`Poll error: ${data.request}`);
  }

  throw new Error("Solve timed out");
}

الأسئلة الشائعة

هل ‏‎CAPCHA_NOT_READY‎‏ خطأ؟

لا، فهذا يعني أن الحل لا يزال قيد التقدم. انتظر 5 ثوان وقم بالاستطلاع مرة أخرى. وهذا أمر طبيعي لكل نوع من أنواع CAPTCHA.

ماذا علي أن أفعل عندما أحصل على ERROR_CAPTCHA_UNSOLVABLE؟

أرسل مهمة جديدة بمعلمات جديدة. لا تقم بإعادة المحاولة باستخدام نفس معرف المهمة. إذا حدث الخطأ بشكل متكرر، فتأكد من صحة مفتاح الموقع وعنوان URL الخاص بك ومن دعم نوع CAPTCHA.

كيف أعرف إذا كان الخطأ قابلاً لإعادة المحاولة؟

لا يمكن إعادة محاولة أخطاء المعلمة/format (ERROR_WRONG_USER_KEY، ERROR_BAD_TOKEN_OR_PAGEURL، ERROR_PAGEURL، وما إلى ذلك) - قم بإصلاح الطلب أولاً. يمكن إعادة محاولة أخطاء الخادم (ERROR_SERVER_ERROR، ERROR_INTERNAL_SERVER_ERROR) مع التراجع الأسي. يمكن إعادة محاولة ERROR_ZERO_BALANCE بعد انتظار تحرير سلاسل الرسائل.

لماذا أحصل على ERROR_BAD_PROXY مقابل Cloudflare Challenge؟

يتطلب Cloudflare Challenge وكيلًا صالحًا للعمل. يجب أن يكون الوكيل قادرًا على الوصول إلى الموقع المستهدف. اختبره بشكل مستقل، ثم جرب وكيلًا مختلفًا إذا فشل. تأكد أيضًا من تمكين استخدام الوكيل على حساب CaptchaAI الخاص بك.

أين يمكنني العثور على مفتاح API الخاص بي؟

تسجيل الدخول إلىcaptchaai.comواذهب الىcaptchaai.com/api.php. يتم عرض مفتاح API المكون من 32 حرفًا على لوحة المعلومات.

أدلة ذات صلة

• حدود الطلب المتزامن CaptchaAI: التشخيص والإصلاحات
• معالجة أخطاء عنوان URL لرد الاتصال CaptchaAI: إعادة المحاولة وأنماط الأحرف الميتة