ERROR_PAGEURL: Hướng dẫn khắc phục sự cố URL không khớp

Gặp ERROR_PAGEURL dù URL trông có vẻ đúng? Trước khi đào sâu, kiểm tra nhanh ba điều sau — phần lớn trường hợp được xử lý ngay ở bước này vì CaptchaAI xác thực token theo đúng domain gốc, lệch một ký tự là bị từ chối.

• Giao thức: pageurl đã bắt đầu bằng https:// chưa, hay thiếu hẳn?
• Domain: bạn gửi đúng bản www hoặc không-www mà trình duyệt đang hiển thị chưa?
• Thời điểm: đây có phải URL tại đúng lúc CAPTCHA xuất hiện, hay là URL trước khi trang chuyển hướng?

6 nguyên nhân phổ biến khiến pageurl bị từ chối

• Thiếu giao thức — gửi example.com thay vì https://example.com
• Sai tên miền — nhầm www.example.com với example.com
• Redirect đổi URL — biểu mẫu tại /login bị chuyển hướng sang /auth/login
• Route SPA không khớp — route JS /app/login không trùng URL máy chủ trả về
• URL chưa mã hoá — dấu cách hoặc ký tự đặc biệt chưa được encode
• Iframe khác domain — CAPTCHA được tải từ một tên miền phụ khác trang chính

Một đội QA tại TP.HCM từng gặp đúng lỗi đầu tiên: script kiểm thử form đăng ký gửi pageurl thiếu https://, khiến toàn bộ token bị từ chối cho tới khi thêm đúng giao thức.

Mẹo: copy nguyên văn URL từ thanh địa chỉ trình duyệt, đừng gõ lại bằng tay — một dấu gạch chéo thừa hoặc thiếu cũng đủ gây ERROR_PAGEURL.

Quy tắc duy nhất bạn cần nhớ khi lấy pageurl

Luôn dùng đúng URL hiển thị trên thanh địa chỉ trình duyệt tại thời điểm CAPTCHA xuất hiện — không phải URL bạn nghĩ trang sẽ có, không phải endpoint mà form gửi tới.

# WRONG — incomplete URL
pageurl = "staging.example.com/qa-login"

# WRONG — wrong protocol
pageurl = "https://staging.example.com/qa-login"

# CORRECT — full URL with protocol
pageurl = "https://staging.example.com/qa-login"

# CORRECT — with www if that's what the page uses
pageurl = "https://staging.example.com/qa-login"

Viết hàm kiểm tra pageurl trước khi gửi request

Chặn lỗi này trước khi gửi request bằng một hàm validate đơn giản:

from urllib.parse import urlparse

def validate_pageurl(url):
    """Validate pageurl before API submission."""
    parsed = urlparse(url)

    if not parsed.scheme:
        raise ValueError(f"Missing protocol: {url}. Use https://")

    if parsed.scheme not in ("http", "https"):
        raise ValueError(f"Invalid protocol: {parsed.scheme}")

    if not parsed.netloc:
        raise ValueError(f"Missing domain: {url}")

    # Remove fragment (hash) — not sent to server
    clean = f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
    if parsed.query:
        clean += f"?{parsed.query}"

    return clean

# Usage
url = validate_pageurl("https://staging.example.com/qa-login#section")
# Returns: "https://staging.example.com/qa-login"

Gọi hàm này ở ba chỗ để chặn lỗi sớm nhất có thể:

• Ngay trước mỗi lần gọi in.php trong pipeline tự động hoá
• Sau khi trích xuất URL động từ DOM hoặc router phía client
• Trong bước kiểm thử CI, để chặn cấu hình sai trước khi chạy thật

Theo dõi redirect trước khi gửi pageurl

Nếu trang chuyển hướng sau khi tải, pageurl phải là URL cuối cùng, không phải URL gõ vào ban đầu:

import requests

def get_final_url(url):
    """Follow redirects to get the actual page URL."""
    resp = requests.get(url, allow_redirects=True, timeout=15)
    return resp.url

# If the login page redirects
original = "https://staging.example.com/qa-login"
final = get_final_url(original)
print(f"Final URL: {final}")
# Use final URL as pageurl

SPA (Single Page Application): lấy route nào?

SPA đổi URL bằng JavaScript mà không tải lại trang. CaptchaAI cần domain hiển thị trên thanh địa chỉ, không phải endpoint API mà form gọi ngầm:

# For SPAs, use the domain root + the route shown in the address bar
# NOT the API endpoint that the form submits to

# WRONG — API endpoint
pageurl = "https://api.example.com/v1/auth/login"

# CORRECT — the page URL shown in browser
pageurl = "https://staging.example.com/qa-login"

CAPTCHA trong iframe: dùng URL trang chính, không phải iframe src

Khi CAPTCHA tải trong iframe từ domain khác, pageurl vẫn phải là URL trang chính:

# If the CAPTCHA is on the MAIN page
pageurl = "https://example.com/register"  # Main page URL

# If the CAPTCHA is in an IFRAME with a different domain
# Still use the main page URL, not the iframe src
pageurl = "https://example.com/register"
# NOT: "https://captcha-frame.example.com/challenge"

Quy tắc: pageurl luôn là URL của trang cha (top-level) mà người dùng đang xem, bất kể CAPTCHA render bên trong iframe nào.

Gửi request hoàn chỉnh tới in.php

Ghép validate_pageurl() vào request thật trước khi gửi:

import requests

# Validate URL first
pageurl = validate_pageurl("https://staging.example.com/qa-login")

resp = requests.post("https://ocr.captchaai.com/in.php", data={
    "key": "YOUR_API_KEY",
    "method": "userrecaptcha",
    "googlekey": "SITE_KEY",
    "pageurl": pageurl,
    "json": 1,
})
result = resp.json()

if result.get("status") == 1:
    print(f"Task ID: {result['request']}")
else:
    print(f"Error: {result.get('request')}")

Phân biệt ERROR_PAGEURL với các mã lỗi khác

ERROR_PAGEURL thường bị nhầm với các lỗi tham số khác. Bảng dưới đây giúp xác định đúng nguyên nhân trước khi sửa sai chỗ:

Bảng tra cứu nhanh: triệu chứng → nguyên nhân → cách xử lý

Câu hỏi thường gặp về ERROR_PAGEURL

pageurl chỉ cần đúng domain hay phải đúng toàn bộ đường dẫn?

Domain là phần bắt buộc để CaptchaAI xác thực token. Tuy nhiên nên gửi đủ đường dẫn vì một số trang xác thực cả URL đầy đủ, không chỉ domain gốc.

Có nên giữ lại tham số truy vấn trong pageurl không?

Giữ lại nếu chúng thuộc URL hiển thị trên trình duyệt. Có thể bỏ tham số theo dõi như utm_source.

ERROR_PAGEURL có phải do sai API key hoặc sitekey không?

Không. ERROR_PAGEURL chỉ liên quan đến pageurl — sai key hoặc googlekey trả về mã lỗi khác (ERROR_WRONG_USER_KEY, ERROR_WRONG_GOOGLEKEY).

Trang chạy qua CDN hoặc proxy thì pageurl phải lấy theo domain nào?

Luôn lấy domain người dùng thấy trên thanh địa chỉ trình duyệt, không phải domain gốc phía sau CDN — CaptchaAI xác thực theo URL hiển thị công khai.

pageurl có cần trùng khớp chữ hoa/chữ thường không?

Domain không phân biệt hoa thường theo chuẩn DNS, nhưng đường dẫn (path) có thể phân biệt hoa thường tuỳ cấu hình server — an toàn nhất là giữ nguyên định dạng như trình duyệt hiển thị.

Hướng dẫn liên quan

• Chẩn đoán WRONG_GOOGLEKEY
• Xác thực tham số BAD_PARAMETERS

Lấy đúng pageurl ngay từ đầu — giải CAPTCHA với CaptchaAI.