# Mã lỗi

> Ý nghĩa và cách xử lý tất cả mã lỗi của YesCaptcha API, chia theo nhóm: định dạng yêu cầu, tài khoản và số dư, giới hạn đồng thời và tạm dừng, kết quả tác vụ, tham số trang web, hình ảnh, proxy, phía máy chủ. Yêu cầu trả về lỗi không bị trừ điểm.

Source: https://docs.yescaptcha.com/vi/api/errors/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/

Khi giao diện gặp lỗi, API trả về `errorId: 1`; `errorCode` là mã lỗi, `errorDescription` là mô tả bằng văn bản. Yêu cầu trả về lỗi không bị trừ điểm: lỗi xảy ra ngay lúc tạo tác vụ thì không trừ, còn tác vụ nhận dạng thất bại hoặc hết thời gian sau khi đã tạo sẽ tự động hoàn điểm.

> **Mẹo:** Trong chương trình, hãy xử lý theo `errorCode`, đừng dựa vào nội dung của `errorDescription`, vì mô tả văn bản có thể thay đổi.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}
```

## Nguyên tắc xử lý

1.  **Lỗi tham số** (định dạng yêu cầu, clientKey, loại tác vụ, tham số trang web, hình ảnh): gửi lại vẫn không đổi kết quả, cần sửa yêu cầu trước.
2.  **Nhận dạng thất bại và hết thời gian** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`): có thể tạo lại tác vụ.
3.  Sau khi gặp lỗi, hãy **dừng polling** `taskId` đó, đừng gửi lại nguyên yêu cầu với tần suất cao.
4.  Với lỗi được đánh dấu “Tính vào tự động tạm dừng”: nếu cùng một `clientKey` gặp 100 lỗi như vậy trong một phút, việc tạo tác vụ sẽ bị tạm dừng 5 phút. Lỗi được đánh dấu “Cache” thì không được tính, nhưng trong thời gian cache, cùng một yêu cầu sẽ trả về ngay lỗi ban đầu. Xem chi tiết tại [Giới hạn đồng thời và tự động tạm dừng](https://docs.yescaptcha.com/vi/api/rate-limits.md).

## Tất cả mã lỗi

### Định dạng yêu cầu

| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Thiếu một trường bắt buộc (như `clientKey`, hoặc `websiteURL` / `websiteKey` theo loại tác vụ), hoặc nội dung yêu cầu không phải JSON | Bổ sung các trường còn thiếu được liệt kê trên trang loại tác vụ, và gửi JSON bằng `POST` kèm `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Tính vào tự động tạm dừng) | Nội dung yêu cầu không phải JSON hợp lệ | Tạo nội dung yêu cầu bằng thư viện JSON thay vì ghép chuỗi; JSON không được chứa chú thích `//` |
| `ERROR_TASK_ABSENT` (Tính vào tự động tạm dừng) | Thiếu trường `task` trong lệnh gọi `createTask` | Đặt các tham số của tác vụ vào đối tượng `task`. Với Python requests hãy dùng `json=data`, không dùng `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Tính vào tự động tạm dừng) | `task.type` bị sai chính tả hoặc loại tác vụ này đã ngừng cung cấp | Sao chép tên loại tác vụ từ "Loại tác vụ và bảng giá"; tên phân biệt chữ hoa chữ thường |
| `ERROR_PAGE_NOT_FOUND` | Đường dẫn được yêu cầu không tồn tại | Kiểm tra URL endpoint, ví dụ `https://api.yescaptcha.com/createTask`; tên phương thức phân biệt chữ hoa chữ thường |
| `ERROR_BAD_REQUEST` | Không thể xử lý yêu cầu, thường do dùng sai phương thức HTTP (GET thay vì POST) hoặc giá trị tham số không hợp lệ | Gửi JSON bằng `POST`, và kiểm tra kiểu cũng như giá trị của các tham số |
| `ERROR_ILLEGAL_PARAMETERS` | Giá trị tham số không hợp lệ. Thường gặp với trang thử thách Cloudflare: `websiteURL` không phải URL công khai bắt đầu bằng `http://` / `https://`, `postData` không phải đối tượng, hoặc `requiredCookies` không phải mảng chuỗi (do createTask trả về, không trừ điểm); hoặc không phân giải được tên miền đích qua proxy (do getTaskResult trả về, đã tự động hoàn điểm) | Sửa giá trị theo bảng tham số trên trang loại tác vụ. Nếu không phân giải được tên miền, hãy kiểm tra chính tả URL và xem proxy có truy cập được website đó không |

### Tài khoản và số dư

| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Tính vào tự động tạm dừng) | `clientKey` không tồn tại: bị thừa hoặc thiếu ký tự khi sao chép, hoặc khóa đã được đặt lại trong bảng điều khiển | Sao chép lại khóa từ bảng điều khiển trên yescaptcha.com, không kèm dấu cách hoặc ký tự xuống dòng |
| `ERROR_KEY_EXPIRED` (Tính vào tự động tạm dừng) | `clientKey` đã hết hạn (do createTask và getBalance trả về, không trừ điểm). Có hai trường hợp: `clientKey` không được sử dụng trong thời gian dài nên hệ thống đã đặt thời hạn để bảo vệ tài khoản (sẽ có email nhắc trước khi hết hạn), hoặc thời hạn được đặt cho `clientKey` này đã qua | Đăng nhập vào bảng điều khiển trên yescaptcha.com. Nếu `clientKey` hết hạn do lâu không sử dụng, hãy tạo `clientKey` mới; số dư sẽ tự động chuyển sang `clientKey` mới. Nếu đã đặt thời hạn, hãy thay đổi thời hạn hoặc dùng `clientKey` khác. Sau đó cập nhật `clientKey` mới vào chương trình của bạn |
| `ERROR_KEY_IP_NOT_ALLOWED` | `clientKey` này có danh sách IP được phép (allowlist) và IP gửi yêu cầu không nằm trong danh sách đó (được trả về bởi createTask và getBalance, không trừ điểm, không tính vào tự động tạm dừng) | Đăng nhập vào bảng điều khiển yescaptcha.com và thêm IP công khai của máy đang gửi yêu cầu vào danh sách IP được phép của `clientKey` này, hoặc dùng `clientKey` khác. Nếu gọi API từ nhiều máy, hãy thêm IP công khai của từng máy (đây là IP gọi API của YesCaptcha, không phải proxy trong tham số tác vụ) |
| `ERROR_KEY_QUOTA_EXCEEDED` | `clientKey` này có hạn mức chi tiêu và phần còn lại của chu kỳ hiện tại ít hơn số điểm cần trừ cho tác vụ này (được trả về bởi createTask, không trừ điểm, không tính vào tự động tạm dừng). Hạn mức tính theo số điểm thực tế đã trừ; điểm được hoàn lại do tác vụ thất bại hoặc hết thời gian chờ cũng được trả về hạn mức | Đăng nhập vào bảng điều khiển yescaptcha.com và tăng hạn mức của `clientKey` này, hoặc chờ chu kỳ tiếp theo (đặt lại hằng ngày, vào thứ Hai hằng tuần hoặc ngày 1 hằng tháng, theo giờ Bắc Kinh; hạn mức dùng một lần không được đặt lại), hoặc dùng `clientKey` khác. `getBalance` trả về hạn mức còn lại của `clientKey` này (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Số dư không đủ. Số dư phải lớn hơn 10 điểm mới tạo được tác vụ | Nạp tiền rồi thử lại. Dùng `getBalance` để kiểm tra số dư |

### Giới hạn đồng thời và tạm dừng

| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Một số trường hợp tính vào tự động tạm dừng) | Tài khoản có quá nhiều tác vụ loại này đang được xử lý. `limit` trong phản hồi là giới hạn hiện tại. Yêu cầu không được xử lý và không bị trừ điểm | Chờ các yêu cầu đang xử lý trả về, hoặc chờ 1–2 giây rồi thử lại; hãy giới hạn số yêu cầu cùng chờ kết quả tại một thời điểm |
| `ERROR_IP_BLOCKED_5MIN` | `clientKey` này gây ra quá nhiều lỗi trong thời gian ngắn và đã bị tự động tạm dừng. `retryAfter` là số giây còn lại và `blockReason` là mã lỗi gây ra việc tạm dừng | Sửa yêu cầu theo `blockReason` và chờ `retryAfter` giây; việc tiếp tục gửi trong thời gian tạm dừng không làm kéo dài thời gian đó |
| `ERROR_NO_SLOT_AVAILABLE` | Dịch vụ nhận dạng tạm thời quá tải. Khi `createTask` trả về lỗi này thì không trừ điểm; tác vụ xếp hàng quá lâu cũng sẽ trả về lỗi này từ `getTaskResult`, và được hoàn điểm tự động | Chờ vài giây rồi tạo lại tác vụ |

### Tác vụ và kết quả

| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Tính vào tự động tạm dừng) | `taskId` không tồn tại, đã hết hạn (kết quả được lưu khoảng 10 phút), thuộc về `clientKey` khác, hoặc được tạo trên endpoint còn lại | Dừng polling tác vụ này. Truy vấn bằng đúng endpoint và `clientKey` đã dùng để tạo tác vụ |
| `ERROR_TASK_TIMEOUT` | Tác vụ không hoàn thành trong thời gian quy định (thường là 110 giây); điểm đã được hoàn tự động | Tạo tác vụ mới; nếu liên tục hết thời gian chờ, hãy thử loại tác vụ khác cho cùng loại captcha |
| `ERROR_CAPTCHA_UNSOLVABLE` | Lần này không nhận dạng được captcha; điểm đã được hoàn. Lỗi này không được tính vào tự động tạm dừng | Tạo tác vụ mới. Nếu vẫn liên tục thất bại, hãy kiểm tra `websiteURL`, `websiteKey` và các tham số khác, hoặc thử loại tác vụ khác cho cùng loại captcha |
| `ERROR_SETTLEMENT_FAILED` (Tính vào tự động tạm dừng) | Số dư không đủ tại thời điểm quyết toán nên không trả về kết quả | Nạp tiền rồi tạo tác vụ mới |
| `ERROR_NO_SUCH_CAPCHA_ID` | Tác vụ không còn hiệu lực | Dừng polling tác vụ này và tạo tác vụ mới |
| `ERROR_RECAPTCHA_TIMEOUT` | Nhận dạng captcha bị hết thời gian chờ; điểm đã được hoàn | Tạo tác vụ mới |

### Tham số website đích

| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (Dùng bộ nhớ đệm, không tính vào tạm dừng) | `websiteKey` không hợp lệ | Tìm lại sitekey trong trang web (xem các hướng dẫn tìm tham số). Trong thời gian lưu cache, các yêu cầu giống hệt sẽ trả về ngay lỗi này, kèm `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (Dùng bộ nhớ đệm, không tính vào tạm dừng) | Tên miền của `websiteURL` không khớp với `websiteKey` | Điền `websiteURL` là địa chỉ trang hiển thị captcha |
| `ERROR_INVALID_KEY_TYPE` (Dùng bộ nhớ đệm, không tính vào tạm dừng) | Sitekey thuộc về loại captcha khác, ví dụ dùng key của v3 cho loại tác vụ v2 | Hãy xác định loại captcha trước (xem "Xác định loại captcha") rồi chọn loại tác vụ tương ứng; với v2 ẩn (invisible), hãy truyền `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (Dùng bộ nhớ đệm, không tính vào tạm dừng) | Trang web này hiện chưa được hỗ trợ | Thử loại tác vụ khác cho cùng loại captcha, hoặc liên hệ bộ phận hỗ trợ |
| `ERROR_HIGH_DEMAND_DOMAIN` (Tính vào tự động tạm dừng) | Trang web này hiện chưa được hỗ trợ | Ngừng gửi tác vụ cho trang web này và liên hệ bộ phận hỗ trợ để xác nhận |
| `ERROR_FAILED_LOADING_WIDGET` | Không tải được captcha với các tham số đã cung cấp | Kiểm tra `websiteURL` và `websiteKey`; với các loại tác vụ dùng proxy riêng, kiểm tra proxy có truy cập được trang web đích hay không |

### Hình ảnh

| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Tính vào tự động tạm dừng) | Ảnh trống hoặc quá nhỏ | Kiểm tra dữ liệu Base64 đã đầy đủ chưa và không có tiền tố `data:image/...;base64,` |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Tính vào tự động tạm dừng) | Ảnh quá lớn | Nén hoặc thu nhỏ ảnh rồi gửi lại; toàn bộ nội dung yêu cầu không được vượt quá 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Tính vào tự động tạm dừng) | Định dạng ảnh không được hỗ trợ, hoặc ảnh không phải loại mà loại tác vụ này xử lý được. Chỉ cần xảy ra 1 lần là bị tạm dừng 30 phút | Dùng JPG hoặc PNG và đảm bảo ảnh phù hợp với loại tác vụ, ví dụ nhận dạng hình ảnh reCAPTCHA cần ảnh 100x100, 300x300 hoặc 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Tính vào tự động tạm dừng) | Kích thước ảnh không đáp ứng yêu cầu của loại tác vụ này | Điều chỉnh kích thước ảnh theo mô tả ở trang loại tác vụ |
| `ERROR_PARSE_IMAGE_FAIL` | Không giải mã được ảnh, thường do Base64 bị cắt cụt hoặc có tiền tố | Kiểm tra mã hóa Base64 và xóa tiền tố `data:` cùng các ký tự xuống dòng |
| `ERROR_UNKNOWN_QUESTION` | `question` bị sai, hoặc câu hỏi này hiện chưa được hỗ trợ | Đối chiếu với danh sách câu hỏi ở trang loại tác vụ. Với câu hỏi chưa được hỗ trợ, hãy liên hệ bộ phận hỗ trợ; câu hỏi mới thường được hỗ trợ trong vòng 3 ngày làm việc |
| `ERROR_UNKNOW_450x450_QUESTION` | Câu hỏi này hiện chưa được hỗ trợ với ảnh 4x4 (450x450) | Tải lại thử thách trên trang để lấy câu hỏi khác |

### Proxy

| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | Proxy từ chối kết nối | Kiểm tra địa chỉ, cổng và giao thức của proxy, và đảm bảo proxy cho phép kết nối từ bên ngoài (không phải địa chỉ cục bộ như 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Kết nối tới proxy bị hết thời gian chờ | Dùng proxy ổn định hơn |
| `ERROR_PROXY_READ_TIMEOUT` | Đọc dữ liệu qua proxy bị hết thời gian chờ | Dùng proxy nhanh hơn |
| `ERROR_PROXY_BANNED` | Proxy không khả dụng, hoặc IP của proxy bị trang web đích chặn | Dùng proxy khác |
| `ERROR_PROXY_INCORRECT` | Tham số proxy sai định dạng | Kiểm tra định dạng của `proxyType`, `proxyAddress`, `proxyPort` (hoặc chuỗi `proxy`) |
| `ERROR_PROXY_TRANSPARENT` | Proxy là proxy trong suốt (transparent) và làm lộ IP thật | Dùng proxy ẩn danh (elite) |
| `ERROR_PROXY_NOT_AUTHORISED` | Tên người dùng hoặc mật khẩu của proxy không đúng | Kiểm tra `proxyLogin` và `proxyPassword` (hoặc thông tin đăng nhập trong chuỗi `proxy`) |
| `ERROR_PROXY_TLS_ERROR` | Bắt tay TLS với proxy thất bại, thường do `proxyType` sai (ví dụ đặt https cho proxy http) | Kiểm tra lại giao thức của proxy |
| `ERROR_PROXY_CONNECTION_FAILED` | Không kết nối được tới máy chủ proxy | Kiểm tra địa chỉ và cổng của proxy, và đảm bảo proxy đang hoạt động bình thường |

### Máy chủ

| Mã lỗi | Ý nghĩa | Cách xử lý |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | Dịch vụ tạm thời không khả dụng (mã lỗi được viết là `UNAVALIABLE`) | Thử lại sau; nếu tiếp tục xảy ra, hãy liên hệ bộ phận hỗ trợ |
| `ERROR_INTERNAL_SERVER_ERROR` | Đã xảy ra lỗi máy chủ nội bộ | Thử lại sau; nếu lỗi vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ và cung cấp `taskId` |
| `ERROR_UNKNOWN` | Lỗi chưa được phân loại | Thử lại sau; nếu lỗi vẫn tiếp diễn, hãy liên hệ bộ phận hỗ trợ và cung cấp `taskId` |

## Trường bổ sung

Phản hồi của một số lỗi có kèm các trường bổ sung:

| Trường | Xuất hiện ở | Mô tả |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, các lỗi được cache | Cần chờ thêm bao nhiêu giây |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Mã lỗi đã kích hoạt việc tạm dừng |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Loại yêu cầu, URL và sitekey của yêu cầu đã kích hoạt tạm dừng, giúp xác định nguyên nhân |
| `cached` | Các lỗi được cache | `true` nghĩa là đây là kết quả được cache, chưa thực sự nhận dạng |
| `badRequest` | Các lỗi được cache | Tham số đã trúng cache |
| `limit` | `ERROR_THREADS_MAXIMUM` | Giới hạn đồng thời hiện tại của bạn |

Quy tắc về ngôn ngữ của `errorDescription` xem tại [Yêu cầu và phản hồi](https://docs.yescaptcha.com/vi/api/overview.md).