Common Grid Image CAPTCHA Errors and Fixes

Grid image CAPTCHA solving can fail due to image quality, format mismatches, or incorrect solution application. Here are the most common errors and how to resolve them.

Image submission errors

ERROR_WRONG_FILE_EXTENSION

Cause: The uploaded file is not a valid image format.

Fix:

• Use PNG or JPEG format only
• Verify the base64 string is properly encoded
• Remove the data:image/...;base64, prefix before sending

# WRONG — includes data URI prefix
body = "data:image/png;base64,iVBORw0KGgo..."

# CORRECT — raw base64 only
body = "iVBORw0KGgo..."

ERROR_TOO_BIG_CAPTCHA_FILESIZE

Cause: Image exceeds the maximum file size (typically 600KB).

Fix:

from PIL import Image
import io
import base64

# Resize if too large
img = Image.open("captcha.png")
if img.width > 600:
    ratio = 600 / img.width
    img = img.resize((600, int(img.height * ratio)), Image.LANCZOS)

buffer = io.BytesIO()
img.save(buffer, format="PNG")
b64 = base64.b64encode(buffer.getvalue()).decode()

ERROR_ZERO_CAPTCHA_FILESIZE

Cause: Empty file or failed image extraction.

Fix:

• Verify the image element has loaded before extracting
• Check that the src attribute is not empty
• Wait for lazy-loaded images

from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

# Wait for image to load
WebDriverWait(driver, 10).until(
    lambda d: d.find_element(By.CSS_SELECTOR, ".captcha img").get_attribute("complete") == "true"
)

Solving errors

ERROR_CAPTCHA_UNSOLVABLE

Cause: The image is too blurry, distorted, or the objects are unrecognizable.

Fix:

• Capture the image at full resolution — do not downscale
• Ensure no overlays or watermarks obscure the grid
• Retry with a fresh captcha (some challenges are inherently ambiguous)

Wrong cells identified

Cause: Low image quality or partial capture.

Fix:

• Screenshot the entire captcha element, including borders
• Do not crop too tightly — include a few pixels of margin
• Verify by saving the captured image and reviewing it manually

# Take a proper element screenshot
captcha_el = driver.find_element(By.CSS_SELECTOR, "#captcha-container")
captcha_el.screenshot("debug_captcha.png")

# Open and check manually
from PIL import Image
Image.open("debug_captcha.png").show()

Solution application errors

Off-by-one index errors

Cause: Mismatch between 1-based API response and 0-based array indexing.

# API returns "1,3,5" (1-based)
solution = "1,3,5"
indices = [int(i) for i in solution.split(",")]

# DON'T: use directly as array index
# cells[1], cells[3], cells[5]  ← WRONG (off by one)

# DO: convert to 0-based
for idx in indices:
    cells[idx - 1].click()  # 1→0, 3→2, 5→4

Cells do not respond to clicks

Cause: Click target is wrong — overlay, iframe, or shadow DOM.

Fix:

# Check if captcha is in an iframe
iframes = driver.find_elements(By.TAG_NAME, "iframe")
for iframe in iframes:
    if "captcha" in iframe.get_attribute("src").lower():
        driver.switch_to.frame(iframe)
        break

# Now find and click cells
cells = driver.find_elements(By.CSS_SELECTOR, ".grid-cell")

Dynamic grid — tiles change after clicking

Cause: reCAPTCHA-style dynamic grids replace tiles.

Fix: Use the token method instead of the image method for reCAPTCHA:

# Token method handles dynamic grids automatically
response = requests.get("https://ocr.captchaai.com/in.php", params={
    "key": API_KEY,
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
    "json": 1
})

Timeout errors

Captcha expires before solution returns

Cause: Grid CAPTCHAs typically expire in 2–3 minutes.

Fix:

• Submit the image immediately after capture
• If the solve takes more than 60 seconds, refresh and retry

CAPCHA_NOT_READY loops indefinitely

Cause: The task may have failed silently.

Fix: Set a maximum retry count and handle failures:

for attempt in range(30):
    time.sleep(5)
    result = requests.get("https://ocr.captchaai.com/res.php", params={
        "key": API_KEY, "action": "get", "id": task_id, "json": 1
    }).json()

    if result.get("status") == 1:
        return result["request"]
    if result.get("request") not in ["CAPCHA_NOT_READY"]:
        break  # Actual error, stop polling

raise Exception("Grid captcha solve failed — refresh and retry")

Debugging checklist

FAQ

What image format gives the best results?

PNG produces the best results because it is lossless. JPEG works but heavy compression can blur cell boundaries and reduce accuracy.

Should I include the instruction text with grid images?

For method=post with recaptcha=1, the instruction is not required — the solver identifies objects visually. For method=bls, always include the instruction text.

Can I solve multiple grid CAPTCHAs in parallel?

Yes. Each solve is independent. Submit multiple tasks and poll each one separately.

What if the grid has non-standard dimensions?

CaptchaAI analyzes the image as-is. Non-standard grids (e.g., 5×3, 2×4) are handled based on visual analysis rather than fixed grid assumptions.

Related guides

• How to Solve Grid Image CAPTCHA Automatically
• How Grid Image CAPTCHA Challenges Work
• CaptchaAI Error Codes Reference