Lỗi API
Mọi endpoint dưới https://litport.net/api/v1 (Token và mức sử dụng, Gói và Trả theo GB) đều trả lỗi theo định dạng JSON mô tả trên trang này. Lỗi của chính kết nối qua proxy dùng mã lỗi proxy bằng số riêng, và API proxy miễn phí công khai không nằm trong phạm vi trang này.
Cấu trúc lỗi#
{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication failed.",
"requestId": "req_example",
"docsUrl": "https://litport.net/docs/api/errors",
"retryable": false
}
}
Cùng request ID đó xuất hiện trong header X-Request-ID. Hãy ghi lại nó cùng mã trạng thái HTTP và mã lỗi. Không bao giờ ghi header Authorization vào log.
Mã 409 kèm thời gian chờ còn có thêm nextChangeAt, một dấu thời gian UTC theo ISO-8601: CHANGE_LIMIT đối với vị trí hoặc IP mới của token.
retryable luôn có mặt, là true hoặc false. true nghĩa là chính yêu cầu đó, gửi lại không đổi sau Retry-After (hoặc nextChangeAt, khi lỗi có trường này), có thể thành công và an toàn để gửi lại: chưa có gì được thực hiện (RATE_LIMITED, CONCURRENT_CHANGE, CHANGE_LIMIT, ALLOWANCE_CONFLICT), hoặc đó là mã 503 trên một yêu cầu an toàn để lặp lại. false nghĩa là phải thay đổi điều gì đó trước: yêu cầu, tài khoản hoặc token. Mã 503 trên một yêu cầu không an toàn để lặp lại cũng là false: hãy đọc trạng thái hiện tại trước khi quyết định (xem Thuật toán thử lại).
Bảng mã trạng thái#
| Trạng thái | Mã | Việc client cần làm |
|---|---|---|
400 |
INVALID, INVALID, INVALID, INVALID_TYPE, INVALID, INVALID, INVALID, INVALID, INVALID, INVALID, INVALID_POOL, INVALID, INVALID, GEO, GEO, INVALID_IP, IPV6, INVALID, INVALID, INVALID, INVALID, INVALID, INVALID, INVALID, INVALID, FIELD |
Sửa yêu cầu. Không thử lại yêu cầu đó khi chưa đổi gì. |
401 |
UNAUTHORIZED |
Cung cấp API key còn hiệu lực theo cơ chế Bearer. Phản hồi không cho biết key hoặc người dùng có tồn tại hay không. |
402 |
INSUFFICIENT |
Nạp tiền vào số dư, rồi gửi lại yêu cầu. Chỉ việc tạo proxy và bật proxy mới cần có số dư. |
403 |
ACCOUNT |
Không được tạo proxy hay bật proxy khi tài khoản đang bị chặn. Liên hệ hỗ trợ. |
404 |
TOKEN, PACKAGE |
Kiểm tra ID và quyền sở hữu. Phản hồi không tiết lộ token hay gói của người dùng khác. |
404 |
NOT_FOUND |
Sửa lại route; route này không tồn tại. |
405 |
METHOD |
Dùng một trong các phương thức nêu trong header Allow. |
409 |
NOT, PACKAGE, CONCURRENT, LOCATION, NOT, CHANGE_LIMIT, ALLOWED, TOKEN, TOKEN, ALLOWANCE, POOL |
Xem phần chi tiết tương ứng bên dưới; CONCURRENT và ALLOWANCE nghĩa là thử lại cùng yêu cầu, CHANGE_LIMIT nghĩa là chờ đến nextChangeAt được báo rồi thử lại; cả ba đều có retryable: true. |
413 |
INVALID |
Nội dung yêu cầu vượt quá 4 KiB. Hãy gửi nội dung nhỏ hơn. |
415 |
INVALID |
Gửi Content-Type: application cho thao tác ghi có nội dung yêu cầu. |
429 |
RATE_LIMITED |
Tuân theo Retry-After và dùng giãn cách thử lại có jitter. retryable là true. |
503 |
SERVICE, TOKEN, ALLOWED |
Tuân theo Retry-After. Thử lại với giãn cách có giới hạn khi retryable là true, rồi liên hệ hỗ trợ kèm request ID. |
Thuật toán thử lại#
Chỉ tự động thử lại khi retryable là true: chờ theo Retry-After (và theo nextChangeAt, khi lỗi có trường này), thêm jitter, rồi gửi lại cùng yêu cầu. Giới hạn số lần thử và để bên gọi thấy được tổng ngân sách thử lại. Khi retryable là false, hãy thay đổi điều gì đó trước, hoặc, sau một lỗi không rõ ràng của yêu cầu không an toàn để lặp lại (xem bên dưới), đọc trạng thái hiện tại trước khi quyết định.
Mọi thao tác ghi trong API này đều an toàn để lặp lại, trừ new-ip, POST /tokens không có externalRef, POST /tokens/{tokenId}/credentials không có requestId, PUT /tokens/{tokenId}/location với {"random": true}, và hai lệnh POST của API hỗ trợ (POST /support/conversations và POST /support/conversations/{conversationId}/messages). Mọi thao tác ghi khác nhận 409 CONCURRENT_CHANGE hoặc một phản hồi không rõ ràng (hết thời gian chờ, mất phản hồi, 503) đều có thể gửi lại, vì lần ghi mới nhất luôn thắng và mọi thao tác ghi khác không có tác dụng nếu đã được áp dụng. Mã 503 trên một yêu cầu không an toàn để lặp lại có retryable: false, vì công việc có thể đã được thực hiện trước khi xảy ra lỗi.
Với new-ip trên token tĩnh, kết quả không rõ ràng nghĩa là đọc GET /tokens/{tokenId}/location trước và chỉ thử lại khi nextChangeAt chưa muộn hơn thời điểm hiện tại. Lặp lại mù quáng trong vòng một tuần chỉ trả về 409 CHANGE_LIMIT.
Một lệnh tạo an toàn để lặp lại khi có externalRef: lần lặp trả về proxy đã tồn tại. Nếu không có, lần lặp có thể tạo proxy thứ hai. Một lệnh cấp lại an toàn để lặp lại khi có requestId: lần lặp trả về thông tin đăng nhập mà lần gọi đầu đã cấp. Nếu không có, lần lặp cấp thêm một cặp khác. Xem Tạo và quản lý proxy.
Trên token xoay, new-ip không thể được xác nhận từ GET /tokens/{tokenId}/location: canChangeNow và nextChangeAt của nó nói về vị trí và không cho biết gì về thời gian chờ giữa các IP mới. Gửi lại sau Retry-After là vô hại; nó chỉ cấp thêm một IP mới khác. Mã 409 CHANGE_LIMIT ngay sau khi mất phản hồi không chứng minh thay đổi đã xảy ra, vì phản hồi 409 LOCATION_UNAVAILABLE cũng làm tiêu hao thời gian chờ.
PUT /tokens/{tokenId}/location với {"random": true} chọn một vị trí mới mỗi lần, nên lần lặp lại sẽ chuyển proxy một lần nữa ở mọi nơi không có thời gian chờ. Sau khi mất phản hồi, hãy đọc GET /tokens/{tokenId}/location trước và chỉ gửi lại nếu proxy không ở vị trí bạn muốn. Hai lệnh POST của API hỗ trợ không có khóa idempotency, và 503 có thể xảy ra sau khi tin nhắn đã được lưu: hãy đọc cuộc trò chuyện trước khi gửi lại tin nhắn.
Chi tiết các mã lỗi#
Nội dung yêu cầu không hợp lệ#
400 khi nội dung yêu cầu không phân tích được thành JSON hoặc không qua được kiểm tra cấu trúc riêng của endpoint (ví dụ, PUT /tokens/{tokenId}/rotation cần đúng {"intervalSec": <integer>}). Với POST /tokens, PATCH /tokens/{tokenId} và POST /tokens/{tokenId}/credentials, nội dung yêu cầu phải là một đối tượng JSON chỉ chứa các trường mà lệnh gọi đó nhận, và PATCH cần ít nhất một trường. 413 khi nội dung yêu cầu vượt quá 4 KiB.
Content type không hợp lệ#
INVALID_CONTENT_TYPE nghĩa là một thao tác ghi có nội dung yêu cầu được gửi mà không có Content-Type: application/json.
Giới hạn không hợp lệ#
INVALID_LIMIT nghĩa là limit không phải số nguyên từ 1 đến 100.
Cursor không hợp lệ#
INVALID_CURSOR nghĩa là cursor dạng opaque bị sai định dạng, bị sửa, không xác thực được, hoặc được cấp cho một endpoint khác. Hãy bắt đầu lại phân trang mà không có cursor.
Loại không hợp lệ#
INVALID_TYPE nghĩa là type trên GET /tokens không phải unlimited hoặc ppg.
Trạng thái không hợp lệ#
INVALID_STATUS nghĩa là status trên GET /tokens không phải active, expired hoặc disabled.
ID token không hợp lệ#
INVALID_TOKEN_IDS nghĩa là tokenIds trên GET /usage không phải danh sách ID proxy dương, hoặc nêu nhiều hơn 100 ID.
ID gói không hợp lệ#
INVALID_PACKAGE_ID nghĩa là bộ lọc packageId trên GET /tokens không phải số nguyên dương. Một packageId trong đường dẫn URL không bao giờ là 400: ID không rõ hoặc của người khác là 404 PACKAGE_NOT_FOUND.
Khoảng thời gian không hợp lệ#
INVALID_TIME_RANGE nghĩa là một dấu thời gian không phải UTC chuẩn, from không trước to, hoặc khoảng thời gian yêu cầu quá lớn.
Nhóm theo không hợp lệ#
INVALID_GROUP_BY nghĩa là groupBy không phải hour, day hoặc month.
Include không hợp lệ#
INVALID_INCLUDE nghĩa là phần mở rộng được yêu cầu không tương thích với token hoặc cách nhóm; các thành phần phí cần token PPG và nhóm theo giờ.
Pool không hợp lệ#
INVALID_POOL nghĩa là pool trên GET /pay-per-gb/geo, POST /tokens hoặc PATCH /tokens/{tokenId} bị thiếu ở nơi bắt buộc, bị trống, hoặc chứa một auth key không khớp với pool nào mà khách hàng được chọn.
Cấp độ không hợp lệ#
INVALID_LEVEL nghĩa là level không phải một trong các giá trị mà endpoint đó chấp nhận: region/city cho các tùy chọn vị trí của token, hoặc country/region/city cho geo trả theo GB.
Cấp cha không hợp lệ#
INVALID_PARENT nghĩa là thiếu địa lý cấp cha bắt buộc: location/options?level=city của token cần region; GET /pay-per-gb/geo cần country cho level=region và cho level=city.
Geo chưa được bật#
GEO_NOT_ENABLED nghĩa là một pool được yêu cầu đã tắt chọn theo vị trí.
Cấp độ geo không được hỗ trợ#
GEO_LEVEL_UNSUPPORTED nghĩa là một pool được yêu cầu không hỗ trợ level được yêu cầu. Hãy kiểm tra geoLevels của pool trong Trả theo GB.
IP không hợp lệ#
INVALID_IP nghĩa là địa chỉ được cung cấp không phải một IPv4 công khai chính xác.
IPv6 không được hỗ trợ#
IPV6_UNSUPPORTED nghĩa là một địa chỉ IPv6 đã được gửi tới thao tác ghi IP được phép của gói; hãy liên hệ hỗ trợ.
Vị trí không hợp lệ#
INVALID_LOCATION nghĩa là vùng, thành phố hoặc nhà mạng được yêu cầu không phải giá trị token này dùng được, hoặc country được gửi bằng giá trị khác "us".
Chu kỳ xoay không hợp lệ#
INVALID_ROTATION nghĩa là intervalSec trên PUT /tokens/{tokenId}/rotation không phải một trong các options được liệt kê của token.
Nhãn không hợp lệ#
INVALID_LABEL nghĩa là label không phải văn bản tối đa 255 ký tự, hoặc null để xóa nhãn.
Tham chiếu ngoài không hợp lệ#
INVALID_EXTERNAL_REF nghĩa là externalRef không phải 1 đến 128 ký tự in được.
Request ID không hợp lệ#
INVALID_REQUEST_ID nghĩa là requestId trên POST /tokens/{tokenId}/credentials không phải 1 đến 64 ký tự gồm chữ cái, chữ số, dấu gạch dưới hoặc dấu gạch nối.
Giá trị enabled không hợp lệ#
INVALID_ENABLED nghĩa là enabled không phải true hoặc false.
Thời hạn không hợp lệ#
INVALID_EXPIRY nghĩa là expiresAt không phải ngày giờ ISO 8601 có múi giờ, hoặc một ngày, nằm trong tương lai, hoặc null.
Hạn mức không hợp lệ#
INVALID_ALLOWANCE nghĩa là allowanceBytes không phải số nguyên tối thiểu 1 (byte), hoặc null để gỡ giới hạn lưu lượng.
Trường không được phép#
FIELD_NOT_ALLOWED nghĩa là PATCH /tokens/{tokenId} đã gửi cho proxy của một gói một trường khác label. Proxy của gói được bật và tắt theo gói đó.
Chưa xác thực#
UNAUTHORIZED bao gồm các key bị thiếu, sai định dạng, không rõ, đã đổi và không có chủ sở hữu mà không cho biết trường hợp nào đã xảy ra.
Không tìm thấy token#
TOKEN_NOT_FOUND bao gồm tokenId bị thiếu, không thuộc sở hữu hoặc không phân tích được trên mọi route của token. Phản hồi giống hệt nhau trong mọi trường hợp, nên không bao giờ tiết lộ token của người dùng khác.
Không tìm thấy gói#
PACKAGE_NOT_FOUND bao gồm packageId bị thiếu, không thuộc sở hữu hoặc không phân tích được trên mọi route của gói, kể cả IP được phép của gói.
Không tìm thấy#
NOT_FOUND nghĩa là route /api/v1 được yêu cầu không tồn tại.
Phương thức không được phép#
METHOD_NOT_ALLOWED nghĩa là một endpoint đã biết nhận phương thức không được hỗ trợ. Phản hồi nêu các phương thức được hỗ trợ trong Allow.
Không được hỗ trợ#
NOT_SUPPORTED nghĩa là token này không có điều khiển đó: không đổi được vị trí, không đổi được chu kỳ xoay, hoặc (new-ip) nó không phải proxy datacenter hay ISP. Chu kỳ xoay của token “Đa vị trí” luôn trả NOT_SUPPORTED, vì chiếc điện thoại chứa proxy quyết định chu kỳ này. DELETE /tokens/{tokenId} trên proxy của một gói cũng trả lỗi này: chỉ proxy trả theo GB mới xóa được.
Số dư không đủ#
INSUFFICIENT_BALANCE là 402. Việc tạo proxy và bật proxy cần số dư dương. Mọi việc khác vẫn chạy khi số dư bằng không: tắt, đổi nhãn, đổi ngày hết hạn hoặc giới hạn, cấp lại thông tin đăng nhập và xóa.
Tài khoản bị cấm#
ACCOUNT_BANNED là 403. Tài khoản bị chặn không thể tạo proxy hay bật proxy. Tắt, cấp lại thông tin đăng nhập và xóa vẫn chạy. Hãy liên hệ hỗ trợ.
Đã đạt giới hạn token#
TOKEN_LIMIT_REACHED nghĩa là tài khoản đã có số proxy trả theo GB tối đa được phép giữ. Hãy xóa một proxy bạn không còn dùng, hoặc liên hệ hỗ trợ để nâng giới hạn.
Token không sửa được#
TOKEN_NOT_EDITABLE nghĩa là proxy không còn sửa được nữa, chẳng hạn vì nó đã bị xóa trong lúc thao tác ghi đang chạy. Không có gì thay đổi. Hãy đọc proxy để xem trạng thái hiện tại.
Xung đột hạn mức#
ALLOWANCE_CONFLICT nghĩa là không lưu được giới hạn lưu lượng. Không có gì thay đổi. Hãy gửi lại cùng yêu cầu.
Cần pool cho xác thực bằng IP#
POOL_REQUIRED_FOR_IP_AUTH nghĩa là pool: null đã được gửi cho một proxy đăng nhập bằng IP được phép. Proxy đó giữ một pool.
Gói không hoạt động#
PACKAGE_INACTIVE nghĩa là kỳ đã thanh toán của token hoặc gói hiện không còn hoạt động.
Thay đổi đồng thời#
CONCURRENT_CHANGE nghĩa là một thao tác ghi khác lên cùng token hoặc gói đã tới cùng lúc. Hãy thử lại cùng yêu cầu.
Vị trí không khả dụng#
LOCATION_UNAVAILABLE nghĩa là vị trí được yêu cầu hiện không có IP dùng được hoặc thiết bị đang hoạt động. Không có gì thay đổi.
Không ở vị trí dự phòng#
NOT_IN_FALLBACK là phản hồi của POST /tokens/{tokenId}/location/return khi token không nằm ngoài vị trí đã lưu, nên không có gì để chuyển về. Lần lặp lại một yêu cầu đã thành công sẽ rơi vào đây và không cấp IP thứ hai. Không có gì thay đổi.
Giới hạn thay đổi#
CHANGE_LIMIT nghĩa là hạn mức đổi hoặc thay thế đã được dùng: một lần mỗi tuần cho IP mới hoặc đổi vị trí của proxy datacenter/ISP tĩnh, một lần mỗi 48 giờ cho việc đổi vị trí của proxy Di động dùng chung tiêu chuẩn tại Mỹ. Với IP mới trên token datacenter/ISP xoay, thời gian chờ là giá trị ngắn nhất trong rotation.options của token, tính từ yêu cầu gần nhất. Lỗi này kèm nextChangeAt và Retry-After tương ứng.
Đã đạt giới hạn IP được phép#
ALLOWED_IPS_LIMIT_REACHED nghĩa là danh sách IP được phép của gói đã đạt limit (1 hoặc 50). Hãy liên hệ hỗ trợ để nâng giới hạn.
Vượt giới hạn tần suất#
RATE_LIMITED nghĩa là API key (với GET /usage, giới hạn riêng 10 yêu cầu mỗi 60 giây), với thao tác ghi IP được phép là gói, hoặc với POST /tokens là tài khoản (giới hạn tạo proxy mới mỗi phút, dùng chung cho mọi key của tài khoản và bảng điều khiển), đã dùng hết cửa sổ hiện tại. Chưa có gì được thực hiện. Hãy tuân theo Retry-After; retryable là true.
Dịch vụ không khả dụng#
SERVICE_UNAVAILABLE nghĩa là một thành phần mà API phụ thuộc tạm thời không khả dụng. Hãy tuân theo Retry-After. retryable là false khi yêu cầu không an toàn để lặp lại; xem Thuật toán thử lại.
Dữ liệu token không hợp lệ#
TOKEN_DATA_INVALID nghĩa là siêu dữ liệu đã lưu của token tạm thời không đọc được. Hãy thử lại sau, rồi báo request ID.
IP được phép không khả dụng#
ALLOWED_IPS_UNAVAILABLE nghĩa là kho lưu trữ IP được phép, cấu hình hoặc việc cấp cổng không khả dụng, kể cả khi một gói tạm hết cổng có thể gán.
Lỗi xác thực#
API cố ý trả cùng một cấu trúc 401 cho các key sai định dạng, không rõ, đã đổi và không có chủ sở hữu. Hãy tạo hoặc đổi API key trong Cài đặt. Việc đổi key làm key đang dùng trước đó mất hiệu lực ngay lập tức.