# Mã lỗi

Trang này liệt kê các mã lỗi thường gặp mà API MoreLogin trả về.

## Định dạng phản hồi

Mọi phản hồi của API đều theo định dạng chuẩn sau:

```json
{
  "code": 0,
  "msg": null,
  "data": {},
  "requestId": "unique-request-id"
}
```

| Trường | Kiểu | Mô tả |
|  --- | --- | --- |
| `code` | integer | `0` = thành công, `>0` = lỗi |
| `msg` | string | Thông báo lỗi (null khi thành công) |
| `data` | object | Dữ liệu phản hồi |
| `requestId` | string | Định danh yêu cầu duy nhất dùng để chẩn đoán |


## Cách nhận biết mã lỗi thuộc lĩnh vực nào

Mã lỗi không được cấp từ một dãy phẳng duy nhất. Mỗi lĩnh vực sản phẩm có một khoảng riêng, nên hai hoặc ba chữ số đầu cho bạn biết hệ thống con nào đã từ chối yêu cầu:

| Khoảng | Lĩnh vực |
|  --- | --- |
| `14xxx` | Proxy |
| `15xxx` | Nhóm và thẻ |
| `19xxx` | Profile trình duyệt |
| `20xxx` | Ví, đơn hàng và tính phí |
| `21001` | Phiên bản client quá cũ |
| `33xxx` | Cloud Phone |
| `35xxx` | Xác thực API và giới hạn tần suất |
| `39xxx` | Cloud Storage |
| `40xxx` | Runtime của Cloud Browser |
| `41xxx` | Cấu hình webhook |
| `99xxx` | Gateway và kiểm tra yêu cầu |


Mỗi endpoint đều liệt kê những mã mà nó được biết là có thể trả về. Xem các bảng theo từng sản phẩm được liên kết từ [bảng thử lại và hoàn tất theo endpoint](/vi/api-reference/getting-started/endpoint-behavior).

## Mã lỗi chung

Bất kỳ endpoint nào cũng có thể trả về, vì chúng đến từ việc kiểm tra yêu cầu, kiểm tra quyền và gateway, không phải từ logic nghiệp vụ.

| Mã | Mô tả | Cách xử lý |
|  --- | --- | --- |
| `0` | Thành công | — |
| `21001` | Phiên bản client quá cũ | Hãy cập nhật client desktop của MoreLogin |
| `35000` | Yêu cầu tới API quá thường xuyên | Hãy thử lại các tác vụ phù hợp với backoff kèm jitter; xem [Giới hạn tần suất](/vi/api-reference/getting-started/rate-limits) |
| `99000` | Lỗi hệ thống không xác định | Hãy thử lại sau và cung cấp `requestId` cho bộ phận hỗ trợ |
| `99001` | Tham số yêu cầu không hợp lệ | Hãy kiểm tra định dạng phần thân và các trường bắt buộc |
| `99002` | Không có quyền thực hiện | Hãy kiểm tra quyền của tài khoản bạn |
| `99003` | Ngoại lệ trong yêu cầu | Hãy điều chỉnh nghiệp vụ cần thiết theo `msg` |
| `99004` | Phần thân yêu cầu quá lớn | Hãy giảm kích thước phần thân yêu cầu |
| `99005` | Đã có một yêu cầu giống vậy đang xử lý | Hãy đợi yêu cầu đang chạy kết thúc rồi thử lại |
| `99006` | Yêu cầu không hợp lệ | Hãy kiểm tra phương thức HTTP, header và phần thân |
| `99007` | IP của yêu cầu không nằm trong danh sách cho phép | Hãy thêm IP gọi vào danh sách cho phép |
| `99008` | Vượt hạn mức số yêu cầu theo IP hoặc thiết bị | Hãy giảm lượng yêu cầu từ IP hoặc thiết bị này |
| `99009` | Quá nhiều yêu cầu | Hãy chờ theo backoff kèm jitter rồi thử lại |
| `99011` | Dấu thời gian của yêu cầu đã hết hạn | Hãy gửi lại với dấu thời gian hiện tại |
| `99012` | Cần quyền chi phí | Hãy dùng tài khoản chủ nhóm, hoặc cấp quyền chi phí |


### Cloud Phone (`33xxx`)

| Mã | Mô tả | Cách xử lý |
|  --- | --- | --- |
| `20002` | The original monthly order was cancelled | Create a new monthly purchase for eligible Cloud Phones |
| `20003` | The original monthly order was refunded | Create a new monthly purchase for eligible Cloud Phones |
| `20004` | The original monthly order does not exist | Verify the Cloud Phone purchase state and contact support with `requestId` if it persists |
| `20008` | The original monthly order is not completed or its status cannot be confirmed | Check the order and Cloud Phone state before retrying |
| `20055` | A Cloud Phone does not exist, was deleted, or does not belong to the team | Verify every Cloud Phone ID and team ownership |
| `20068` | A pending monthly payment order already exists | Complete or cancel the pending order before using the activation API |
| `20070` | A concurrent Cloud Phone purchase is already in progress | Wait for the in-flight purchase to settle, then read state before retrying |
| `20071` | A selected monthly SKU is unavailable or has no active 30-day price | Query the monthly SKU endpoint again and choose an available product |
| `33420` | Paid and unpaid Cloud Phones cannot be activated in the same batch | Separate Cloud Phones by purchase state and submit compatible batches |
| `33421` | Paid Cloud Phones from different purchase orders cannot be mixed | Submit one activation batch per original purchase order |
| `33422` | Payment succeeded but activation is incomplete or cannot yet be confirmed | Inspect `data.results` and each Cloud Phone's expiry state; do not pay again blindly |
| `33300` | Cloud Phone không tồn tại | Hãy kiểm tra ID Cloud Phone và xem nó có thuộc nhóm của bạn không |
| `33301` | Cloud Phone chưa bật | Hãy bật máy và đợi tới trạng thái có thể chạy |
| `33308` | Thành viên khác đang dùng, không thể tắt nguồn | Hãy thử lại khi thành viên kia giải phóng máy |
| `33309` | Thành viên khác đang dùng, không thể kết nối | Hãy thử lại khi thành viên kia giải phóng máy |
| `33315` | Tài khoản đang nợ phí, Cloud Phone bị đóng băng | Hãy nạp tiền vào ví |
| `33316` | Không đủ profile khả dụng | Hãy nâng cấp gói |
| `33317` | Quyền với profile đã bị thu hồi | Hãy nhờ quản trị viên cấp quyền truy cập |
| `33318` | Số dư không đủ để bật máy | Hãy nạp tiền vào ví |
| `33321` | Profile không khả dụng | Hãy kiểm tra trạng thái profile trước khi thử lại |
| `33322` | Đang kiểm tra proxy | Hãy hỏi vòng cho đến khi việc kiểm tra hoàn tất |
| `33323` | Profile đang khởi động | Hãy đợi khởi động xong; đừng gửi lại |
| `33324` | Profile đã đang chạy | Không cần làm gì |
| `33325` | Profile đã bị vô hiệu hóa | Hãy kích hoạt lại trước khi dùng |
| `33331` | Đang đổi thiết bị một cú nhấp, không thể tắt nguồn | Hãy đợi hoàn tất |
| `33332` | Đang khởi động lại, không thể tắt nguồn | Hãy đợi hoàn tất |
| `33333` | Đang khôi phục cài đặt, không thể tắt nguồn | Hãy đợi hoàn tất |
| `33338`–`33345` | Thiếu hoặc không hợp lệ quốc gia, múi giờ, ngôn ngữ, kinh độ hoặc vĩ độ | Xem [bảng quốc gia và múi giờ](/vi/api-reference/appendix/country-time-zone) |
| `33346` | SKU đã ngừng bán | Hãy chọn một `skuId` khác |
| `33347` | Dòng máy này yêu cầu client Windows bản mới nhất | Hãy cập nhật client desktop của MoreLogin |
| `33367` | Đang bảo trì, không thể bật máy | Hãy xem thông báo hệ thống để biết thời điểm khôi phục |
| `33376` | Kỳ tính phí theo tháng đã hết | Hãy gia hạn đăng ký |
| `33398`–`33400` | Kinh độ, vĩ độ hoặc độ cao ngoài phạm vi | Kinh độ −180…180, vĩ độ −90…90, độ cao −50000…100000 |
| `33401` | Cloud Phone không hỗ trợ tác vụ này | Hãy dùng dòng máy được hỗ trợ |
| `33407` | Vượt hạn mức gói chạy song song | Hãy đợi có suất trống hoặc tăng hạn mức |
| `33408` | Định dạng số điện thoại không hợp lệ | Bắt đầu bằng `+`, mã quốc gia 1–3 chữ số không gồm 86, tổng cộng 8–14 chữ số |
| `33418` | Tệp phát trực tiếp không tồn tại hoặc không hợp lệ | Hãy tải lên với `uploadType=2` và dùng `fileId` được trả về |
| `33419` | Định dạng tệp phát trực tiếp không được hỗ trợ | Hãy tải lên tệp MP4 qua `/cloudphone/uploadFile` |
| `33005` | Cài đặt ứng dụng thất bại | Hãy thử lại và kiểm tra dung lượng lưu trữ trên thiết bị |
| `33014` | Tác vụ quá thường xuyên | Hãy chờ theo backoff rồi thử lại |
| `33714` | Ứng dụng không tồn tại hoặc đã bị gỡ khỏi kho | Hãy làm mới thư viện ứng dụng |
| `33814` | Mẫu RPA không tồn tại | Hãy liệt kê lại các mẫu và dùng `templateId` hiện tại |
| `33818` | Định dạng tham số mẫu RPA không hợp lệ | Hãy gửi `templateParameter` dưới dạng chuỗi JSON đã escape |
| `33303` | Tạo Cloud Phone thất bại | Hãy truy vấn `/cloudphone/page` trước khi thử lại; đừng gửi lại mù quáng |
| `33320` | Proxy gán cho Cloud Phone này đã bị xóa | Hãy gán lại proxy bằng `/cloudphone/setProxy` |
| `33326` | Thành viên khác đang dùng, không thể thay thiết bị | Hãy thử lại khi thành viên kia giải phóng máy |
| `33350` | Không bật được ADB trên một số Cloud Phone | Những máy đó không đang chạy hoặc không hỗ trợ ADB; hãy đọc lại trạng thái và chỉ thử lại với chúng |
| `33507` | Tệp không tồn tại trên thiết bị | Hãy kiểm tra đường dẫn; yêu cầu tải về sẽ quét thư mục cha trước khi truyền |


Các tác vụ cài đặt và bật/tắt nguồn còn có thể trả về một mã do dịch vụ thiết bị đối chiếu, thuộc các khoảng `33001`–`33033`, `33500`–`33520`, `33700`–`33724` hoặc `33900`–`33910`. Mã nào có thể xảy ra phụ thuộc vào dịch vụ thiết bị đang phục vụ thiết bị, nên các endpoint không liệt kê riêng từng mã.

### Profile trình duyệt (`19xxx`)

| Mã | Mô tả | Cách xử lý |
|  --- | --- | --- |
| `19001` | Tên profile đã tồn tại | Hãy chọn một tên duy nhất, hoặc bỏ trống `envName` để hệ thống tự sinh |
| `19002` | Việc tạo profile thất bại ở phía dưới | Hãy xác nhận bằng `/env/page` trước khi thử lại |
| `19004` | Định dạng user agent không hợp lệ | Hãy gửi `advancedSetting.ua` có thể phân tích được |
| `19005` | Định dạng cookie không hợp lệ | Hãy gửi `cookies` dưới dạng chuỗi mảng JSON đã escape |
| `19039` | Không tìm thấy profile | Hãy kiểm tra `envId` / `uniqueId` và xem nó có thuộc nhóm của bạn không |
| `19063` | Đã đạt giới hạn số lượng profile | Hãy xóa profile hoặc nâng cấp gói |
| `19064` | Không có quyền với nhóm này | Hãy nhờ quản trị viên cấp quyền truy cập nhóm |
| `19065` | Không có quyền với profile này | Hãy nhờ quản trị viên cấp quyền truy cập profile |
| `19099` | Không đủ profile khả dụng, việc sử dụng bị hạn chế | Hãy nâng cấp gói |
| `19100` | ID nền tảng không hợp lệ | Hãy dùng `platformId` do `/system/platform/list` trả về |
| `19101` | ID site không hợp lệ | Hãy dùng `siteId` do `/system/platform/list` trả về |
| `19102` | URL nền tảng tùy chỉnh không được để trống | Hãy gửi `platformUrl` khi `platformId` là `9999` |
| `19103` | Định dạng URL mở tự động không hợp lệ | Hãy gửi các URL tuyệt đối hợp lệ trong `afterStartupConfig` |
| `19104` | ID nhóm không hợp lệ | Hãy dùng một nhóm đang tồn tại trong nhóm làm việc của bạn |
| `19105` | ID thẻ không hợp lệ | Hãy dùng các thẻ đang tồn tại trong nhóm của bạn |
| `19106` | ID proxy không hợp lệ | Hãy dùng một proxy đang tồn tại trong nhóm của bạn, hoặc bỏ trống `proxyId` |
| `19107` | Phiên bản kernel trình duyệt không hợp lệ | Hãy chọn một phiên bản từ `/env/advanced/ua/versions` |
| `19108` | Phiên bản user agent không hợp lệ | Hãy chọn một phiên bản từ `/env/advanced/ua/versions` |
| `19109` | Phiên bản user agent không khớp với user agent | Hãy để `uaVersion` khớp với `advancedSetting.ua`, hoặc chỉ gửi một trong hai |
| `19110` | Định dạng URL tùy chỉnh không hợp lệ | Hãy gửi một URL tuyệt đối hợp lệ |
| `19111` | Firefox chỉ hỗ trợ Windows và macOS | Hãy chọn Windows hoặc macOS, hoặc chuyển sang Chrome |
| `19112` | Chưa thiết lập khóa mã hóa, không thể bật mã hóa profile | Hãy cấu hình khóa mã hóa cho nhóm, hoặc gửi `isEncrypt=0` |
| `19141` | Giới hạn 100 ký tự, chỉ gồm chữ số, chữ cái và dấu cách | Hãy rút ngắn `accountInfo.otpSecret` và bỏ các ký tự khác |
| `19142` | Không thể sửa profile được mã hóa đầu-cuối | Hãy dùng client MoreLogin cho các profile đã mã hóa |
| `19143` | Phiên bản client quá cũ so với kernel | Hãy cập nhật client desktop của MoreLogin |
| `19147` | Vượt giới hạn tạo trong ngày | Hãy nâng cấp gói để tăng giới hạn |
| `19149` | Chưa chọn loại cache nào | Hãy chọn ít nhất một loại cache cần xóa |
| `19159` | Hệ điều hành không khớp với thiết lập nâng cao | Không thể đổi hệ điều hành khi cập nhật; hãy giữ `advancedSetting.os` như đã lưu |
| `19160` | Loại trình duyệt không khớp với thiết lập nâng cao | Không thể đổi trình duyệt khi cập nhật; hãy giữ `advancedSetting.vendor` như đã lưu |
| `19175` | Tọa độ ngoài vùng phục vụ | Hãy chọn tọa độ trong vùng được hỗ trợ |
| `19193` | Bên chia sẻ đã tắt quyền chỉnh sửa profile này | Hãy nhờ chủ sở hữu cho phép chỉnh sửa |


### Cloud Storage (`39xxx`)

| Mã | Mô tả | Cách xử lý |
|  --- | --- | --- |
| `39001` | Không tìm thấy thông tin cloud storage | Hãy kiểm tra xem nhóm đã được cấp cloud storage chưa |
| `39011` | Không tìm thấy tệp | Hãy kiểm tra ID tệp |
| `39014` | URL truy cập tệp đang trống | Hãy đăng ký lại lượt tải lên |
| `39037` | Tham số phần mở rộng tệp không hợp lệ | Hãy gửi một phần mở rộng được hỗ trợ |
| `39041` | Đã đạt hạn mức lưu trữ | Hãy xóa tệp để giải phóng dung lượng |
| `39044` | Tên tệp bị trùng | Hãy đổi tên tệp |
| `39045` | Quá nhiều lượt tải lên đã ký trước đang chờ | Hãy hoàn tất hoặc bỏ các lượt tải lên đang chờ trước |
| `39046` | Tệp chưa được tải lên thành công | Hãy tải tệp lên URL đã ký trước rồi mới gọi complete |
| `39047` | Cloud storage đã hết hạn | Hãy gia hạn cloud storage |
| `39048` | Không tìm thấy thẻ cloud storage | Hãy dùng một thẻ do `/cloudstorage/tag/all` trả về |
| `39049` | ID thẻ không được để trống | Hãy gửi ít nhất một thẻ; mảng rỗng sẽ bị từ chối |
| `39050` | Tên tệp dài hơn 60 ký tự | Hãy rút ngắn tên |
| `39051` | Kích thước tệp phải lớn hơn 0 B và nhỏ hơn 2 GB | Hãy chia nhỏ hoặc nén tệp |


### Proxy (`14xxx`) và ví (`20xxx`)

| Mã | Mô tả | Cách xử lý |
|  --- | --- | --- |
| `14003` | Cập nhật proxy thất bại, hoặc proxy không tồn tại | Hãy kiểm tra ID proxy |
| `14017` | Không thể xóa proxy | Proxy nền tảng cloud chưa hết hạn thì không xóa được; hãy đợi tới khi hết hạn |
| `14023` | Loại proxy không tồn tại | Hãy dùng một giá trị dịch vụ thiết bị được hỗ trợ |
| `14024` | Proxy không tồn tại | Hãy kiểm tra các ID proxy |
| `14519` | Không thể sửa thông tin proxy động | Hãy quản lý proxy động ngoài các endpoint proxy |
| `20018` | Không đọc được giá sản phẩm | Hãy thử lại sau và cung cấp `requestId` cho bộ phận hỗ trợ |
| `20029` | Tài khoản ví không khả dụng | Hãy kiểm tra ví của nhóm |
| `20032` | Truy vấn số dư thất bại | Hãy thử lại sau và cung cấp `requestId` cho bộ phận hỗ trợ |
| `20041` | Số dư không đủ | Hãy nạp tiền vào ví |


### Runtime của Cloud Browser (`40xxx`)

Do `/cloudbrowser/start`, `/cloudbrowser/stop` và `/cloudbrowser/connect` trả về. Những mã phát sinh sau khi yêu cầu khởi động đã được điều phối sẽ hiện ra ở `/cloudbrowser/page`, không phải trong phản hồi khởi động.

| Mã | Mô tả | Cách xử lý |
|  --- | --- | --- |
| `40001` | Cloud browser đã đang chạy | Không cần làm gì; hãy kết nối tới lượt chạy hiện có |
| `40002` | Không thể dừng cloud browser ở trạng thái hiện tại | Hãy đọc lại `/cloudbrowser/page` rồi thử lại |
| `40003` | Kiểm tra proxy thất bại | Hãy xác nhận proxy đã gán có thể kết nối được |
| `40006` | Tác vụ cloud browser thất bại | Hãy thử lại; nếu việc lưu trữ thất bại, xem `cloudBrowserArchiveStatus` |
| `40008` | Không tìm thấy cloud browser nào đang chạy | Hãy khởi động một cái trước, hoặc đọc lại `/cloudbrowser/page` |
| `40009` | Không thể kết nối tới lượt chạy do thành viên khác khởi động | Hãy nhờ thành viên đó giải phóng nó |
| `40010` | Kết nối tới cloud browser thất bại | Hãy thử lại; không phát hành được token truy cập desktop |
| `40015` | Profile chưa được gán proxy | Hãy gán proxy trước bằng `/env/setProxy/batch` |
| `40016` | Không điều phối được yêu cầu khởi động | Hãy thử lại |
| `40020` | Cloud browser đang được dừng | Hãy đợi quá trình dừng hoàn tất |
| `40021` | Cloud browser đã đang khởi động | Đừng gửi lại; hãy hỏi vòng `/cloudbrowser/page` |
| `40023` | Profile đang được sử dụng | Hãy đóng phiên còn lại trước |
| `40024` | Cloud browser không khởi động kịp thời | Hãy khởi động lại |
| `40025` | Proxy đã gán không còn tồn tại | Hãy gán lại proxy |
| `40026` | Proxy đã gán đã hết hạn | Hãy gia hạn hoặc thay proxy |
| `40027` | Proxy đã gán vẫn đang được cấp phát | Hãy thử lại khi việc cấp phát hoàn tất |
| `40028` | Không hỗ trợ proxy cục bộ | Hãy dùng một proxy không phải cục bộ |
| `40029` | Không hỗ trợ loại proxy này | Hãy dùng một loại proxy được hỗ trợ |
| `40037` | Profile mã hóa đầu-cuối không dùng được cloud browser | Hãy dùng một profile không mã hóa |


### Webhook (`41xxx`)

Được trả về bởi các endpoint cấu hình webhook khi URL callback bị từ chối.

| Mã | Mô tả | Cách xử lý |
|  --- | --- | --- |
| `41001` | URL callback phải là địa chỉ HTTPS hợp lệ | Hãy gửi URL HTTPS dài tối đa 1024 ký tự, không chứa thông tin người dùng hay fragment, cổng hợp lệ, và bảo đảm mọi địa chỉ mà nó phân giải ra đều định tuyến được trên internet |


### Xác thực API (`35xxx`) và nhóm (`12xxx`)

| Mã | Mô tả | Cách xử lý |
|  --- | --- | --- |
| `12002` | Nhóm không tồn tại | Nhóm của thành viên đã bị xóa; hãy liên hệ bộ phận hỗ trợ |
| `35002` | Xác thực API thất bại | Hãy kiểm tra `client_id` (API ID) và `client_secret` (API key) |
| `35005` | Yêu cầu không có quyền thực hiện | Thành viên đã bị vô hiệu hóa, hoặc IP gọi không vượt qua danh sách IP cho phép và chặn của Open API |


## Mã trạng thái HTTP

| Trạng thái | Mô tả |
|  --- | --- |
| `200` | Yêu cầu đã được xử lý (xem trường `code` để biết kết quả nghiệp vụ) |
| `401` | Không được xác thực — access token không hợp lệ hoặc đã hết hạn |
| `403` | Bị từ chối — không đủ quyền |
| `429` | Quá nhiều yêu cầu — đã vượt giới hạn tần suất |
| `500` | Lỗi nội bộ của server — hãy liên hệ hỗ trợ |


Gateway ứng dụng hiện tại biểu diễn việc từ chối do giới hạn tần suất của chính nó bằng mã nghiệp vụ `35000` và không đặt HTTP `429` một cách tường minh. Một proxy biên hoặc phiên bản gateway trong tương lai vẫn có thể trả về `429`, nên client nên xử lý cả hai dạng.

## Ngữ nghĩa thử lại và phục hồi

| Loại lỗi | Có thử lại? | Hành vi client bắt buộc |
|  --- | --- | --- |
| Lỗi kiểm tra dữ liệu, quyền, số dư hoặc tính năng không được hỗ trợ | Không | Hãy sửa yêu cầu, quyền, số dư hoặc tài nguyên đã chọn trước khi thử lại |
| Giới hạn tần suất (`35000`) | Có, có điều kiện | Chờ theo cơ chế backoff kèm jitter; kiểm tra `code` trong phần thân ngay cả khi trạng thái HTTP là `200` |
| Lỗi tạm thời của server hoặc dịch vụ thiết bị | Có, có điều kiện | Có thể thử lại các lệnh đọc; với lệnh ghi, hãy truy vấn trạng thái tài nguyên hoặc tác vụ trước |
| Tác vụ không đồng bộ đã được tiếp nhận | Đừng gửi lại ngay | Hãy hỏi vòng endpoint trạng thái được ghi trong tài liệu cho đến khi thành công, thất bại hoặc hết thời gian chờ |
| Không rõ kết quả sau khi hết thời gian chờ mạng | Kiểm tra trạng thái trước | Đừng lặp lại một cách mù quáng việc tạo, mua, đăng ký tải lên hay tạo lịch |


API công khai hiện chưa có header khóa idempotency dùng chung. Vì vậy, việc truy vấn trạng thái theo từng endpoint là một phần của quy trình phục hồi an toàn cho các yêu cầu làm thay đổi trạng thái.

Với tác vụ không đồng bộ, phản hồi `code: 0` có thể nghĩa là «đã tiếp nhận», không phải «đã hoàn tất». Hãy theo tài liệu của endpoint để biết trường trạng thái và các trạng thái kết thúc của nó.

Xem [bảng thử lại và hoàn tất theo endpoint](/vi/api-reference/getting-started/endpoint-behavior) để biết mọi endpoint, và [Tác vụ không đồng bộ](/vi/api-reference/getting-started/async-operations) để biết quy trình hỏi vòng cùng các trạng thái kết thúc.

> **Mẹo**: hãy luôn kèm `requestId` trong phản hồi khi liên hệ hỗ trợ để việc chẩn đoán nhanh hơn.