reCAPTCHA v2 الشائعة لحل الأخطاء والإصلاحات

تنقسم معظم حالات فشل reCAPTCHA v2 إلى ثلاث مجموعات: أخطاء مرحلة الطلب (تم إرسال المعلمات الخاطئة إلى واجهة برمجة التطبيقات)، ومشكلات مرحلة النتيجة (مشكلات الاقتراع أو المهام غير القابلة للحل)، ورفض الصفحة المستهدفة (ترجع واجهة برمجة التطبيقات رمزًا مميزًا صالحًا ولكن الصفحة تتجاهله). أكبر المذنبين هم دائمًا نفس الشيء: خطأ googlekey، أو pageurl غير صحيح، أو تنفيذ رد الاتصال المفقود، أو الرموز المميزة منتهية الصلاحية.

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

أكبر أربع نقاط فشل في reCAPTCHA v2

قبل البحث في رموز الأخطاء الفردية، تحقق منها أولاً، فهي تغطي 80% من حالات الفشل.

1. خطأ أو مفقود googlekey

يأتي googlekey (مفتاح الموقع) من سمة data-sitekey في عنصر واجهة المستخدم reCAPTCHA أو المعلمة k في عنوان URL للارتساء. إذا كانت هذه القيمة خاطئة أو فارغة أو منسوخة من صفحة مختلفة، فإن واجهة برمجة التطبيقات (API) ترفض المهمة على الفور باستخدام ERROR_GOOGLEKEY أو ERROR_WRONG_GOOGLEKEY.

كيفية العثور على مفتاح الموقع الصحيح:

# Look for data-sitekey in the page HTML
# <div class="g-recaptcha" data-sitekey="6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-"></div>

# Or find it in the anchor URL
# https://www.google.com/recaptcha/api2/anchor?k=6Le-wvkSVVABCPBMRTvw0Q4Muexq1bi0DJwx_mJ-

2. خطأ pageurl

يجب أن يكون pageurl هو عنوان URL الدقيق حيث يتم تحميل أداة reCAPTCHA. إذا كانت الأداة موجودة داخل إطار iframe مستضاف على نطاق مختلف، فستحتاج إلى عنوان URL لـ iframe - وليس عنوان URL للصفحة الرئيسية. يؤدي إرسال عنوان URL الخاطئ إلى ظهور ERROR_PAGEURL أو ERROR_BAD_TOKEN_OR_PAGEURL.

3. لم يتم تنفيذ رد الاتصال

تستخدم بعض الصفحات وظيفة رد اتصال JavaScript بدلاً من حقل g-recaptcha-response المخفي. إذا قمت بإدخال الرمز المميز في الحقل المخفي ولكن الصفحة تتوقع رد اتصال، فلن يتم إرسال النموذج أبدًا. تحقق من وجود data-callback على عنصر واجهة المستخدم أو خاصية callback في grecaptcha.render().

4. انتهت صلاحية الرمز المميز أو أعيد استخدامه

رموز reCAPTCHA صالحة لاستخدام واحد فقط وتنتهي صلاحيتها بعد دقيقتين تقريبًا. إذا استغرقت عملية الأتمتة وقتًا طويلاً بين استلام الرمز المميز وإرسال النموذج، أو إذا أعادت استخدام الرمز المميز، فإن الصفحة المستهدفة ترفضه بصمت.

أخطاء مرحلة الطلب (in.php)

تحدث هذه الأخطاء عند إرسال مهمة CAPTCHA إلى https://ocr.captchaai.com/in.php.

مثال: الطلب الصحيح مع معالجة الأخطاء

import requests

def submit_recaptcha_v2(api_key, sitekey, page_url):
    response = requests.get("https://ocr.captchaai.com/in.php", params={
        "key": api_key,
        "method": "userrecaptcha",
        "googlekey": sitekey,
        "pageurl": page_url,
        "json": 1
    })

    data = response.json()

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

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

    if error == "ERROR_WRONG_USER_KEY":
        raise ValueError("API key format is invalid. Must be 32 characters.")
    elif error == "ERROR_ZERO_BALANCE":
        raise RuntimeError("Account balance is zero. Top up at captchaai.com")
    elif error == "ERROR_PAGEURL":
        raise ValueError("pageurl parameter is missing from request")
    elif error in ("ERROR_GOOGLEKEY", "ERROR_WRONG_GOOGLEKEY"):
        raise ValueError(f"Invalid sitekey. Verify the data-sitekey value on the page.")
    elif error == "ERROR_BAD_TOKEN_OR_PAGEURL":
        raise ValueError("Sitekey/pageurl mismatch. Check if widget is in an iframe.")
    else:
        raise RuntimeError(f"API error: {error}")

# Usage
task_id = submit_recaptcha_v2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://example.com/login")
print(f"Task submitted: {task_id}")

async function submitRecaptchaV2(apiKey, sitekey, pageUrl) {
  const params = new URLSearchParams({
    key: apiKey,
    method: "userrecaptcha",
    googlekey: sitekey,
    pageurl: pageUrl,
    json: 1,
  });

  const res = await fetch(`https://ocr.captchaai.com/in.php?${params}`);
  const data = await res.json();

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

  const error = data.request || "UNKNOWN_ERROR";
  const fixes = {
    ERROR_WRONG_USER_KEY: "API key format is invalid. Must be 32 characters.",
    ERROR_ZERO_BALANCE: "Account balance is zero. Top up at captchaai.com",
    ERROR_PAGEURL: "pageurl parameter is missing from request",
    ERROR_GOOGLEKEY: "Invalid sitekey. Check the data-sitekey attribute.",
    ERROR_BAD_TOKEN_OR_PAGEURL: "Sitekey/pageurl mismatch. Check iframe context.",
  };

  throw new Error(fixes[error] || `API error: ${error}`);
}

// Usage
const taskId = await submitRecaptchaV2("YOUR_API_KEY", "6Le-wvkSAAAAAN...", "https://example.com/login");
console.log(`Task submitted: ${taskId}`);

أخطاء مرحلة النتيجة (res.php)

تحدث هذه الأخطاء عند استقصاء https://ocr.captchaai.com/res.php للنتيجة.

مثال: الاقتراع مع معالجة الأخطاء بشكل صحيح

import time
import requests

def poll_result(api_key, task_id, timeout=120):
    start = time.time()

    while time.time() - start < timeout:
        time.sleep(5)

        response = requests.get("https://ocr.captchaai.com/res.php", params={
            "key": api_key,
            "action": "get",
            "id": task_id,
            "json": 1
        })

        data = response.json()

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

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

        if error == "CAPCHA_NOT_READY":
            continue  # normal — keep waiting
        elif error == "ERROR_CAPTCHA_UNSOLVABLE":
            raise RuntimeError("CAPTCHA unsolvable. Submit a new task with fresh params.")
        elif error in ("ERROR_WRONG_ID_FORMAT", "ERROR_WRONG_CAPTCHA_ID"):
            raise ValueError(f"Invalid task ID: {task_id}")
        else:
            raise RuntimeError(f"Polling error: {error}")

    raise TimeoutError(f"Solve timed out after {timeout}s")

# Usage
token = poll_result("YOUR_API_KEY", task_id)
print(f"Token: {token[:50]}...")

async function pollResult(apiKey, taskId, timeout = 120000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    await new Promise((r) => setTimeout(r, 5000));

    const params = new URLSearchParams({
      key: apiKey,
      action: "get",
      id: taskId,
      json: 1,
    });

    const res = await fetch(`https://ocr.captchaai.com/res.php?${params}`);
    const data = await res.json();

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

    if (data.request === "CAPCHA_NOT_READY") continue;
    if (data.request === "ERROR_CAPTCHA_UNSOLVABLE")
      throw new Error("Unsolvable. Submit a new task.");
    throw new Error(`Polling error: ${data.request}`);
  }

  throw new Error(`Solve timed out after ${timeout / 1000}s`);
}

رفض الصفحة المستهدفة

أعادت واجهة برمجة التطبيقات (API) رمزًا مميزًا صالحًا ولكن الموقع المستهدف لا يزال يرفضه. هذه هي أصعب حالات الفشل في تصحيح الأخطاء لأن واجهة برمجة التطبيقات (API) تعتقد أن كل شيء يعمل.

تم إدخال الرمز المميز في الحقل الخطأ

تبحث بعض الصفحات عن الرمز المميز في منطقة النص g-recaptcha-response. يستخدم الآخرون grecaptcha.getResponse(). ويتوقع آخرون رد الاتصال. إذا اخترت طريقة الحقن الخاطئة، فسيفشل إرسال النموذج بصمت.

الإصلاح: فحص الصفحة لتحديد المسار المتوقع:

# Method 1: Hidden field injection
driver.execute_script(
    'document.getElementById("g-recaptcha-response").innerHTML = arguments[0];',
    token
)

# Method 2: Callback execution (check data-callback attribute)
driver.execute_script(f'onCaptchaSuccess("{token}");')

# Method 3: Direct form field + submit
driver.execute_script(
    'document.querySelector("[name=g-recaptcha-response]").value = arguments[0];',
    token
)
driver.find_element("css selector", "form").submit()

لم يتم تشغيل رد الاتصال

إذا كان عنصر واجهة المستخدم يحتوي على data-callback="onSuccess" أو يستخدم grecaptcha.render() مع خاصية callback، فإن ملء الحقل المخفي وحده لا يؤدي إلى أي شيء. يجب عليك استدعاء وظيفة رد الاتصال مباشرة.

الإصلاح: البحث عن رد الاتصال والاتصال به:

// In browser console or Puppeteer/Playwright
// Check for data-callback
const widget = document.querySelector('.g-recaptcha');
const callbackName = widget?.getAttribute('data-callback');
if (callbackName && window[callbackName]) {
  window[callbackName](token);
}

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

إذا مر أكثر من دقيقتين تقريبًا بين استلام الرمز المميز وإرسال النموذج، فإن Google ترفضه. وهذا أمر شائع في خطوط أنابيب الأتمتة البطيئة.

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

القطعة موجودة في إطار iframe

إذا تم تحميل reCAPTCHA داخل iframe من نطاق مختلف، فيجب عليك استخدام عنوان URL لمصدر iframe كـ pageurl، وليس عنوان URL للصفحة الأصلية. عادةً ما يشير الخطأ ERROR_BAD_TOKEN_OR_PAGEURL إلى هذه المشكلة.

الإصلاح: افحص الصفحة، وابحث عن إطار iframe الذي يحتوي على reCAPTCHA، واستخدم عنوان URL src الخاص بـ iframe باعتباره pageurl.

قائمة مرجعية للتشخيص السريع

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

لماذا يفشل reCAPTCHA v2 حتى عندما يبدو الطلب صحيحًا؟

الأسباب الثلاثة الأكثر شيوعًا هي: (1) عدم تطابق pageurl مع سياق الأداة الفعلي - خاصة عندما تكون الأداة داخل iframe، (2) تتوقع الصفحة وظيفة رد اتصال ولكنك ملأت الحقل المخفي فقط، أو (3) انتهت صلاحية الرمز المميز قبل إرسال النموذج.

ما هو الخطأ الأكثر شيوعًا في حل reCAPTCHA v2؟

استخدام googlekey الخاطئ أو pageurl الخاطئ. يعد هذا أمرًا شائعًا بشكل خاص عند تحميل أداة reCAPTCHA في إطار iframe على نطاق أو نطاق فرعي مختلف - يجب أن يتطابق مفتاح الموقع وعنوان URL مع سياق iframe، وليس الصفحة الأصلية.

ماذا يعني CAPCHA_NOT_READY؟

وهذا يعني أن اختبار CAPTCHA لا يزال قيد الحل. هذا ليس خطأ. انتظر 5 ثوان وقم باستطلاع res.php مرة أخرى. تتراوح أوقات حل reCAPTCHA v2 النموذجية بين 15 و60 ثانية.

ماذا علي أن أفعل إذا قامت واجهة برمجة التطبيقات (API) بإرجاع رمز مميز ولكن الصفحة لا تزال ترفضه؟

تحقق من ثلاثة أشياء بالترتيب: (1) هل تستخدم الصفحة رد اتصال؟ ابحث عن data-callback على القطعة. (2) هل pageurl صحيح - خاصة إذا كانت الأداة موجودة في إطار iframe؟ (3) هل مر أكثر من دقيقتين بين استلام الرمز واستخدامه؟

كيف أتعامل مع ERROR_CAPTCHA_UNSOLVABLE؟

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

أصلح سير عمل reCAPTCHA v2

1. التحقق من مدخلاتك — استخرج googlekey من data-sitekey واستخدم عنوان URL الدقيق للصفحة (تحقق من إطارات iframe)
2. تحقق من طريقة الإدخال — حدد ما إذا كانت الصفحة تتوقع حقلاً مخفيًا أو رد اتصال أو كليهما
3. أرسل فورًا — استخدم الرمز خلال دقيقتين من استلامه
4. إضافة معالجة للأخطاء — استخدم أمثلة التعليمات البرمجية أعلاه للتعرف على كل أنواع الأخطاء ومعالجتها

ابدأ في حل reCAPTCHA v2 باستخدامCaptchaAI . احصل على مفتاح API الخاص بك منcaptchaai.com/api.php.

أدلة ذات صلة

• البدء السريع مع CaptchaAI: حلّ أول كابتشا في 5 دقائق
• أخطاء وإصلاحات reCAPTCHA v2 Enterprise الشائعة