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. |
7. (Xfast link point service) API get batch id
https://pro-docs.ghtk.vn/9-g4-api/#321-api-lay-ma-phien-noi-iem
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 422 | 107101 | Vui lòng nhập địa chỉ chi tiết của nơi lấy hàng hóa. | Field first_address is required |
| 422 | 107102 | Vui lòng nhập tên tỉnh/thành phố nơi lấy hàng hóa. | Field province is required |
| 422 | 107103 | Vui lòng nhập tên quận/huyện nơi lấy hàng hóa. | Field district is required |
| 422 | 107104 | Vui lòng nhập tên phường/xã nơi lấy hàng hóa. | Field ward is required |
| 422 | 107105 | Vui lòng nhập tên đường/phố nơi lấy hàng hóa. | Field street is required |
| 422 | 107106 | Vui lòng nhập tên địa chỉ cấp 4 nơi lấy hàng hóa. | Field hamlet is required |
8. (Xfast link point service) API check service available
https://pro-docs.ghtk.vn/9-g4-api/#322-api-kiem-tra-dich-vu-va-cac-iem-co-thoa-man-dich-vu-xfast-noi-iem
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 422 | 107107 | Vui lòng gửi lên ID của batch. | Field batch_id is required |
| 422 | 107108 | Vui lòng kiểm tra địa chỉ chi tiết của nơi lấy hàng hóa. | Field pick_address.first_address is required |
| 422 | 107109 | Vui lòng kiểm tra tên tỉnh/thành phố nơi lấy hàng hóa. | Field pick_address.province is required |
| 422 | 107110 | Vui lòng kiểm tra tên quận/huyện nơi lấy hàng hóa. | Field pick_address.district is required |
| 422 | 107111 | Vui lòng kiểm tra tên phường/xã nơi lấy hàng hóa. | Field pick_address.ward is required |
| 422 | 107112 | Vui lòng kiểm tra tên đường/phố nơi lấy hàng hóa. | Field pick_address.street is required |
| 422 | 107113 | Vui lòng kiểm tra tên địa chỉ cấp 4 nơi lấy hàng hóa. | Field pick_address.hamlet is required |
| 422 | 107114 | Vui lòng kiểm tra khối lượng đơn hàng. | Field deliver_address.*.weight is required |
| 422 | 107115 | Vui lòng nhập mã điểm giao. | Field deliver_address.*.id is required |
| 422 | 107116 | Vui lòng kiểm tra địa chỉ tỉnh/thành phố nhận đơn hàng. | Field deliver_address.*.province is required |
| 422 | 107117 | Vui lòng kiểm tra địa chỉ quận/huyện nhận đơn hàng. | Field deliver_address.*.district is required |
| 422 | 107118 | Vui lòng kiểm tra địa chỉ phường/xã nhận đơn hàng. | Field deliver_address.*.ward is required |
| 422 | 107119 | Vui lòng kiểm tra địa chỉ cấp 4 nhận đơn hàng. | Field deliver_address.*.hamlet is required |
| 422 | 107120 | Vui lòng kiểm tra địa chỉ chi tiết nhận đơn hàng. | Field deliver_address.*.first_address is required |
9. (Xfast link point service) API get fee
https://pro-docs.ghtk.vn/9-g4-api/#324-api-tinh-phi-xfast-noi-iem
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 422 | 107121 | Vui lòng gửi lên ID của batch. | Field batch_id is required |
| 422 | 107144 | Vui lòng kiểm tra địa chỉ chi tiết của nơi lấy hàng hóa. | Field pick_address.first_address is required |
| 422 | 107122 | Vui lòng kiểm tra tên tỉnh/thành phố nơi lấy hàng hóa. | Field pick_address.province is required |
| 422 | 107123 | Vui lòng kiểm tra tên quận/huyện nơi lấy hàng hóa. | Field pick_address.district is required |
| 422 | 107124 | Vui lòng kiểm tra tên phường/xã nơi lấy hàng hóa. | Field pick_address.ward is required |
| 422 | 107125 | Vui lòng kiểm tra tên đường/phố nơi lấy hàng hóa. | Field pick_address.street is required |
| 422 | 107126 | Vui lòng kiểm tra tên địa chỉ cấp 4 nơi lấy hàng hóa. | Field pick_address.hamlet is required |
| 422 | 107127 | Vui lòng kiểm tra khối lượng đơn hàng. | Field pkg_data.*.weight is required |
| 422 | 107128 | Vui lòng nhập mã ID đơn hàng. | Field pkg_data.*.id is required |
| 422 | 107129 | Vui lòng kiểm tra địa chỉ tỉnh/thành phố nhận đơn hàng. | Field pkg_data.*.province is required |
| 422 | 107130 | Vui lòng kiểm tra địa chỉ quận/huyện nhận đơn hàng. | Field pkg_data.*.district is required |
| 422 | 107131 | Vui lòng kiểm tra địa chỉ phường/xã nhận đơn hàng. | Field pkg_data.*.ward is required |
| 422 | 107132 | Vui lòng kiểm tra địa chỉ cấp 4 nhận đơn hàng. | Field pkg_data.*.hamlet is required |
| 422 | 107133 | Vui lòng kiểm tra địa chỉ chi tiết nhận đơn hàng. | Field pkg_data.*.first_address is required |
10. (Xfast link point service) API create order
https://pro-docs.ghtk.vn/9-g4-api/#325-api-ang-on-noi-iem-nhieu-on1-lan
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 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ợ. | Field packages.*.id is required to be unique |
| 422 | 30107 | Quý khách đã dùng mã … cho 1 đơn hàng khác. | Field packages.*.id is required to be unique |
| 422 | 30102 | Trường order.id phải có độ dài dưới 250 kí tự. | Field packages.*.id max length is 250 characters |
| 422 | 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!. | Field packages.*.pick_money invalid |
| 422 | 30301 | Số điện thoại khách hàng không hợp lệ. | Field packages.*.customer_tel invalid |
| 422 | 30201 | Số điện thoại lấy hàng không hợp lệ. | Field pick_address.pick_tel invalid |
| 422 | 30202 | Số điện thoại lấy hàng trùng với số điện thoại nhận hàng | Field pick_address.pick_tel is not allowed equal packages.*.customer_tel |
| 422 | 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! | Field packages.*.value invalid |
| 422 | 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. | Field packages.*.weight invalid |
| 422 | 30106 | Trường is_freeship có giá trị không hợp lệ. | Field packages.*.is_freeship invalid |
| 422 | 30119 | Thiếu thông tin sản phẩm. Vui lòng kiểm tra lại. | Field packages.*.products invalid |
| 422 | 30504 | Tên sản phẩm quá dài. Vui lòng sửa lại. | Field packages.*.products.*.name max length is 500 characters |
| 422 | 30501 | Giá trị số lượng ở sản phẩm .... có giá trị không hợp lệ. | Field packages.*.products.*.quantity invalid |
| 422 | 30103 | Đơn hàng chưa có khối lượng. Vui lòng kiểm tra lại. | Field packages.*.weight invalid |
| 422 | 30203 | Vui lòng nhập mã sản phẩm. | Field packages.*.id is required |
| 422 | 30204 | Vui lòng nhập tên người gửi. | Field pick_address.pick_name is required |
| 422 | 30205 | Vui lòng nhập tiền CoD. | Field packages.*.pick_money is required |
| 422 | 30206 | Vui lòng nhập đúng số tiền CoD. | Field packages.*.pick_money invalid |
| 422 | 30207 | Vui lòng nhập địa chỉ lấy hàng hóa. | Field pick_address.first_address is required |
| 422 | 30208 | Vui lòng nhập tên thành phố nơi lấy hàng hóa. | Field pick_address.province is required |
| 422 | 30209 | Vui lòng nhập tên quận/huyện nơi lấy hàng hóa. | Field pick_address.district = is required |
| 422 | 30210 | Vui lòng nhập điện thoại liên hệ nơi lấy hàng hóa. | Field pick_address.pick_tel is required |
| 422 | 30303 | Vui lòng nhập tên người nhận hàng hóa. | Field packages.*.customer_name is required |
| 422 | 30304 | Vui lòng nhập địa chỉ chi tiết của người nhận hàng hóa. | Field packages.*.customer_first_address is required |
| 422 | 30305 | Vui lòng nhập tên tỉnh/thành phố của người nhận hàng hóa. | Field packages.*.customer_province is required |
| 422 | 30306 | Vui lòng nhập tên quận/huyện của người nhận hàng hóa. | Field packages.*.customer_district is required |
| 422 | 30307 | Vui lòng nhập số điện thoại người nhận hàng hóa. | Field packages.*.customer_tel is required |
| 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á. | Field packages.*.value invalid |
| 422 | 107134 | Mã điểm giao : … đang bị trùng. Vui lòng kiểm tra lại. | Field packages.*.pkg_batch_id is required to be unique |
| 422 | 107135 | Điểm giao … của batch … đã được xử lý. Vui lòng kiểm tra lại. | Field packages.*.pkg_batch_id has been processed |
| 422 | 107136 | Thiếu thông tin BatchId. | Field batch_id is required |
| 422 | 107137 | Thiếu thông tin ID điểm giao. | Field packages.*.pkg_batch_id is required |
| 422 | 107138 | Không tìm thấy thông tin BatchId. | Not found any batch |
| 422 | 107139 | Batch đã được xử lý. Vui lòng kiểm tra lại thông tin BatchId. | Batch has been already processed |
| 422 | 107140 | Không tìm thấy ID điểm giao. Vui lòng kiểm tra lại. | Not found any pkg batch id |
| 422 | 107141 | Điểm giao không tồn tại. Vui lòng kiểm tra lại. | Field packages.*.pkg_batch_id is invalid |
| 422 | 107142 | Điểm giao đã được xử lý. Vui lòng kiểm tra lại. | Pkg Batch Id has been already processed |
| 422 | 107143 | Thiếu thông tin packages. | Field packages is required |