2. Handling errors
Requests made to our APIs can result in several different error responses. The following document describes the recovery tactics and provides a list of error values with a map to the most common recovery tactic to use.
Error Responses
The following represents a common error response resulting from a failed API request:
{
"success": false,
"message": "{ERROR_MESSAGE}",
"error_code": "{ERROR_CODE}",
"log_id": "{LOG_ID}"
}
| Field | Description |
|---|---|
| ERROR_MESSAGE | A human-readable description of the error. |
| ERROR_CODE | An error code. Common values are listed below, along with common recovery tactics. |
| LOG_ID | Log Id to help us find log data for debugging |
Error Codes
1. System errors
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 500 | 10101 | Đã có lỗi xảy ra! | There was an error during execution |
| 405 | 10102 | Phương thức không hợp lệ | HTTP method is wrong |
| 500 | 10103 | Hệ thống GHTK đang sự cố. Bạn vui lòng liên hệ tại địa chỉ sos.ghtk.vn để được hỗ trợ. | There was an error during execution |
| 404 | 10104 | Đường dẫn không tồn tại, vui lòng thử lại sau | The requested resource/page not found. |
| 405 | 10105 | Yêu cầu không hợp lệ | Method Not Allowed |
| 500 | Internal Server Error | The request was not completed due to an internal error on the server side. | |
| 503 | Service Unavailable | The server was unavailable. |
2. Authenticate errors
https://pro-docs.ghtk.vn/#12-token-header
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 401 | 20101 | Cần cung cấp token hợp lệ | Invalid shop token |
| 401 | 20102 | X-Refer-Token không hợp lệ | 401 - x-refer-token is missing information in the request body |
3. API create order
https://pro-docs.ghtk.vn/#21-submit-order-api
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 422 | 30101 | Thiếu thông tin đơn hàng | Field order is missing information in the request body |
| 422 | 30102 | Trường order.id phải có độ dài dưới 250 kí tự. | The long of text of field order.id must be less than 250 characters |
| 422 | 30103 | Đơn hàng chưa có khối lượng. Vui lòng kiểm tra lại. | Field order.total_weight is missing information in the request body |
| 422 | 30104 | Phương thức vận chuyển không hợp lệ, ban chỉ có thể chọn road(đường bộ) hoặc fly(đường bay). | Field order.transport is missing information or the value of field order.transport is invalid in the request body |
| 422 | 30105 | Lưu danh sách đơn hàng không thành công. Hãy thử lại. Đơn hàng có mã là … của khách hàng ..... bị sai khối lượng. GHTK tính theo đơn vị (kg), vui lòng kiểm tra lại thông tin và điền đúng khối lượng của đơn hàng. | Total weight don`t satisfy with the given condition |
| 422 | 30106 | Trường is_freeship có giá trị không hợp lệ. |
The value of field order.is_freeship must be 1 or 0 |
| 422 | 30107 | Quý khách đã dùng mã ...... cho 1 đơn hàng khác. | The value of field order.id has been used |
| 422 | 30108 | Trường pick_option chỉ nhận một trong hai giá trị cod và post, mặc định là cod, biểu thị lấy hàng bởi COD hoặc Shop sẽ gửi tại bưu cục. | The value of field order.pick_option must be cod or post |
| 422 | 30110 | Giá trị hàng hoá phải lớn hơn 0. Shop vui lòng kê khai chính xác giá trị hàng hoá. | The value of field order.value out of range |
| 422 | 30201 | Số điện thoại lấy hàng không hợp lệ. | Field order.pick_tel in the request body is less than 7 characters |
| 422 | 30202 | Số điện thoại lấy hàng trùng với số điện thoại nhận hàng. | The value of field order.tel and order.pick_tel is duplicate |
| 422 | 30203 | Vui lòng nhập mã sản phẩm. | The value of field order.id is missing information |
| 422 | 30204 | Vui lòng nhập tên người gửi. | The value of field order.pick_name is missing information |
| 422 | 30205 | Vui lòng nhập tiền CoD | The value of field order.pick_money is missing information |
| 422 | 30206 | Vui lòng nhập đúng số tiền CoD. | The value of field order.pick_money is invalid |
| 422 | 30207 | Vui lòng nhập địa chỉ lấy hàng hóa. | The value of field order.pick_money is invalid |
| 422 | 30208 | Vui lòng nhập tên thành phố nơi lấy hàng hóa. | The value of field order.pick_money is invalid |
| 422 | 30209 | Vui lòng nhập tên quận/huyện nơi lấy hàng hóa. | The value of field order.pick_money is invalid |
| 422 | 30210 | Vui lòng nhập điện thoại liên hệ nơi lấy hàng hóa. | The value of field order.pick_money is invalid |
| 422 | 30301 | Số điện thoại khách hàng không hợp lệ. | Field order.tel must be greater than 7 characters in the request body |
| 422 | 30302 | Đơn hàng có mã là … của khách hàng … thiếu thông tin địa chỉ thôn/ấp/xóm/tổ/…. Vui lòng kiểm tra lại. | Field order.hamlet is missing information in the request body |
| 422 | 30303 | Vui lòng nhập tên người nhận hàng hóa. | The value of field order.name is missing |
| 422 | 30304 | Vui lòng nhập địa chỉ chi tiết của người nhận hàng hóa. | The value of field order.address is missing |
| 422 | 30305 | Vui lòng nhập tên tỉnh/thành phố của người nhận hàng hóa. | The value of field order.province is missing |
| 422 | 30306 | Vui lòng nhập tên quận/huyện của người nhận hàng hóa. | The value of field district is missing |
| 422 | 30307 | Vui lòng nhập số điện thoại người nhận hàng hóa. | The value of field order.tel is missing |
| 422 | 30401 | Vui lòng nhập tên người nhận hàng trả. | The value of field order.return_name is missing |
| 422 | 30402 | Vui lòng nhập địa chỉ chi tiết của người nhận hàng trả, ví dụ: nhà A, ngõ 100. | Field return_address is missing information in the request body |
| 422 | 30403 | Vui lòng nhập tên tỉnh/thành phố của người nhận hàng trả. | Field order.return_province is missing information in the request body |
| 422 | 30404 | Vui lòng nhập tên quận/huyện của người nhận hàng trả. | Field order.return_district is missing information in the request bodyng |
| 422 | 30405 | Vui lòng nhập số điện thoại người nhận hàng trả. | Field order.return_tel is missing information in the request body |
| 422 | 30501 | Giá trị số lượng ở sản phẩm .... có giá trị không hợp lệ. | The value of field quantity in order.products is invalid |
| 403 | 30601 | Shop chưa được hỗ trợ tính năng này! | The field is_fulfillment and is_economy is invalid for fulfillment order |
| 400 | 30603 | Lưu danh sách đơn hàng không thành công. Hãy thử lại. Đơn hàng có mã là .... của khách hàng .... quá khối lượng. GHTK tính theo đơn vị (kg) và không chuyển hàng > .... kg. | Total weight must be less than given boundary |
| 200 | 30604 | Do tình hình dịch bệnh nên không có chuyến bay phù hợp, bạn vui lòng chọn PTVC Bộ để tiếp tục tạo đơn hàng | Shipping method order.fly will be blocked without shopee express |
| 400 | 30607 | GHTK chưa hỗ trợ giao hàng đơn có số tiền CoD lớn hơn …đ. Mong quý khách thông cảm!. | The value of field order.pick_money is invalid |
| 400 | 30608 | GHTK chưa hỗ trợ giao hàng đơn có giá trị đóng bảo hiểm lớn hơn .....đ. Mong quý khách thông cảm!. | The value of field order.value is invalid |
| 400 | 30609 | Hiện GHTK phát hiện shop gửi mặt hàng không hợp lệ nên tài khoản của shop sẽ bị vô hiệu hóa việc đăng đơn. Vui lòng liên hệ CSKH để được giải đáp | The order is invalid because of the banned goods |
| 200 | 30610 | Tuyến giao đến … đang tạm ngưng nhận đơn … | This address is blocked when you place an order |
4. API print label
https://pro-docs.ghtk.vn/#25-print-package-label
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 500 | 40101 | Has an unexpected errors when print label, please retry this request ! | There was an error during execution |
5. API cancel order
https://pro-docs.ghtk.vn/#24-cancel-order
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 200 | 50101 | Đơn hàng đã ở trạng thái hủy | This order has been cancel before (packages.package_status_id = 11) |
| 200 | 50102 | Đơn đã lấy hàng, không thể hủy đơn. | If the goods has arrived at the warehouse (packages.package_status_id = 3), the OPM order cannot be canceled |
| 200 | 50103 | Đơn đã điều phối giao hàng/đang giao hàng, không thể hủy đơn. | If the goods is delivering (packages.package_status_id = 4), the order cannot be canceled |
| 200 | 50104 | Đơn đã giao hàng/chưa đối soát, không thể hủy đơn. | If the goods is delivered (packages.package_status_id = 5), the order cannot be canceled |
| 200 | 50105 | Đơn đã đối soát, không thể hủy đơn. | If the goods is debt reconciliation (packages.package_status_id = 6), the order cannot be canceled |
| 200 | 50106 | Đơn đã điều phối lấy hàng/đang lấy hàng, không thể hủy đơn. | If the goods is arrving to the warehouse (packages.package_status_id = 12), the order cannot be canceled |
| 200 | 50107 | Không thể hủy đơn hàng .... | The package (order) is invalid |
| 500 | 50108 | Lỗi, vui lòng thử lại sau! | There was an error during order cancellation |
| 400 | 50109 | Không tìm thấy vận đơn trên hệ thống | Not found the order in the system |
6. API calculate shipment fee
https://pro-docs.ghtk.vn/#22-calculate-shipping-fee
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 422 | 60101 | Vui lòng kiểm tra tên tỉnh/thành phố nơi lấy hàng hóa | Please check the province/city name for the pickup location. |
| 422 | 60102 | Vui lòng kiểm tra tên quận/huyện nơi lấy hàng hóa | Please check the district name for the pickup location. |
| 422 | 60103 | Vui lòng kiểm tra tên tỉnh/thành phố của người nhận hàng hóa | Please check the province/city name for the receiver location. |
| 422 | 60104 | Vui lòng kiểm tra tên quận/huyện của người nhận hàng hóa | Please check the district name for the receiver location. |
| 422 | 60105 | Vui lòng kiểm tra thông tin khối lượng đơn hàng. | Please check the weight of order. |