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

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

3. API create order

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 hàng chưa có khối lượng. Vui lòng kiểm tra lạ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 thị lấy hàng bởi COD hoặc Shop sẽ gửi tại bưu cụ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 lòng kiểm tra lạ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

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
200	40102	Mã vận đơn không hợp lệ, không tìm thấy vận đơn !	Order is not recognized / cannot be found

5. API 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

HTTP Code	Error Code	Message	Description
422	Updating ..	Xin hãy gửi trường district.	Field `district` is required
422	Updating ..	Xin hãy gửi trường province.	Field `province` is required
422	Updating ..	Xin hãy gửi trường pick_district.	Field `pick_district` is required
422	Updating ..	Xin hãy gửi trường pick_province.	Field `pick_province` is required

2. Handling errors

Error Responses​

Error Codes​

1. System errors​

2. Authenticate errors​

3. API create order​

4. API print label​

5. API cancel order​

6. API calculate shipment fee​