ERROR_CAPTCHA_UNSOLVABLE do nada, células clicadas na posição errada ou um CAPCHA_NOT_READY que não sai do loop de polling: a maioria dos erros de CAPTCHA de imagem em grade nasce de um destes quatro pontos — formato do arquivo, qualidade da captura, indexação da solução ou expiração do desafio.
Veja a correção direta para cada erro do CaptchaAI, sem abrir chamado de suporte.
Erros ao enviar a imagem do captcha
ERROR_WRONG_FILE_EXTENSION
Causa: o arquivo enviado não está em um formato de imagem válido. Correção: use apenas PNG ou JPEG, confirme que a string base64 está bem codificada e remova o prefixo data:image/...;base64, antes de enviar.
# WRONG — includes data URI prefix
body = "data:image/png;base64,iVBORw0KGgo..."
# CORRECT — raw base64 only
body = "iVBORw0KGgo..."
ERROR_TOO_BIG_CAPTCHA_FILESIZE
Causa: a imagem ultrapassa o tamanho máximo aceito (geralmente 600 KB). Correção: redimensione antes de codificar:
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
Causa: arquivo vazio ou falha na extração da imagem. Correção: confirme que o elemento carregou antes de extrair, verifique se o atributo src não está vazio e aguarde imagens com lazy loading.
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"
)
Por que a resolução falha
ERROR_CAPTCHA_UNSOLVABLE
Causa: a imagem está borrada, distorcida, ou os objetos não são reconhecíveis. Correção: capture a imagem em resolução total (nunca reduza a escala), confirme que nenhuma sobreposição ou marca d'água cobre a grade e tente de novo com um captcha novo — alguns desafios são ambíguos até para um humano.
Células erradas na resposta
Causa: captura parcial ou imagem de baixa qualidade.
Capture todo o elemento do captcha, incluindo as bordas. Não recorte rente demais — deixe alguns pixels de margem e revise a imagem antes de enviar:
# 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()
Erros ao aplicar a solução
Índice deslocado em um (off-by-one)
Causa: a resposta da API é baseada em 1, mas a indexação do array é baseada em 0.
Subtraia 1 de cada índice antes de localizar a célula no array — é a única correção necessária:
# 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
As células não respondem ao clique
Causa: o alvo do clique está errado — sobreposição, iframe ou shadow DOM. Correção: confirme o contexto certo antes de clicar:
# 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")
Grade dinâmica: os blocos mudam depois do clique
Causa: grades dinâmicas ao estilo reCAPTCHA substituem os blocos. Correção: use o método de token em vez do método de imagem para 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
})
Erros de tempo limite e expiração
O captcha expira antes da resposta voltar
Causa: grades de CAPTCHA costumam expirar em 2 a 3 minutos. Correção: envie a imagem imediatamente após capturá-la; se passar de 60 segundos, atualize a página e tente de novo. Worker longe da CaptchaAI? Meça o RTT antes de suspeitar da resolução.
CAPCHA_NOT_READY em loop infinito
Causa: a tarefa pode ter falhado silenciosamente. Correção: defina um número máximo de tentativas e trate as falhas de verdade:
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")
Perguntas frequentes
Por que o ERROR_CAPTCHA_UNSOLVABLE aparece mesmo com uma imagem nítida?
Geralmente porque a instrução visual não corresponde a nenhum objeto reconhecível, ou um elemento (banner, cookies) sobrepõe a grade no print. Capture de novo com a página totalmente carregada.
PNG ou JPEG: qual formato reduz mais os erros de resolução?
PNG, porque não perde informação na compactação. JPEG funciona, mas compressão pesada borra os limites das células e derruba a precisão — evite qualidade abaixo de 85% se optar por JPEG.
Como isolar se a falha é na captura da tela ou no envio para a API?
Salve a imagem em disco antes de codificar em base64 e abra o arquivo manualmente. Se já estiver cortada, borrada ou vazia, o problema está na captura (Selenium, Playwright), não na API.
Dá para enviar vários CAPTCHAs de grade em paralelo sem aumentar a taxa de erro?
Sim. Cada tarefa é independente — enviar em paralelo não aumenta a chance de erro. Faça o polling de cada task_id separadamente e respeite o limite de threads do plano.
Preciso me preocupar com dados pessoais ao salvar prints do captcha para depurar?
Se a captura inclui a página inteira, não só o elemento do captcha, ela pode registrar dados de terceiros. Trate esses arquivos como dado sensível sob a LGPD: limite a retenção e capture só o elemento do captcha (captcha_el.screenshot(...)), não a tela cheia.
Checklist rápido de depuração
Confira estes oito pontos antes de abrir chamado — a maioria dos erros cai em um deles:
- Formato da imagem? PNG ou JPEG, codificado corretamente.
- Tamanho da imagem? Abaixo de 600 KB.
- Grade completa capturada? Grade inteira, com margens.
- Qualidade da imagem? Nítida, sem desfoque ou redução de escala.
- Formato da solução? Índices separados por vírgula, corretos.
- Base do índice? Converter 1-based para 0-based.
- Contexto do iframe? Trocar para o iframe, se houver.
- Captcha expirado? Enviar logo após a captura.
