Mã lỗi
Trong quá trình kết nối hệ thống và sử dụng dịch vụ của OpenAPI có thể phát sinh các lỗi không mong muốn. Tài liệu này sẽ mô tả các mã lỗi xác định đối với mục API đơn hàng của chúng tôi
Mẫu request gặp lỗi
Dưới đây là định dạng của một request gặp sự cố đã xác định :
{
"status": 400,
"message": "Thiếu thông tin địa chỉ",
"error_code": 4010106,
"timestamp": "2025-10-10T11:33:00.458Z"
}
| Trường | Kiểu dữ liệu | Mô tả |
|---|---|---|
| status | integer | Mã HTTP status code của lỗi. Ví dụ: 400 thể hiện lỗi từ phía client (Bad Request). |
| message | string | Thông điệp mô tả ngắn gọn nội dung lỗi để người gọi API có thể hiểu và xử lý. Ví dụ: "Thiếu thông tin địa chỉ". |
| error_code | integer | Mã lỗi nghiệp vụ (business error code) dùng để xác định loại lỗi cụ thể trong hệ thống. Ví dụ: 40002 có thể tương ứng với lỗi “Thiếu thông tin địa chỉ”. |
| timestamp | string (ISO-8601) | Thời điểm hệ thống ghi nhận lỗi, theo định dạng thời gian quốc tế ISO 8601 (UTC). Ví dụ: "2025-10-10T11:33:00.458Z". |
Danh sách mã lỗi
1. Lỗi hệ thống
| HTTP Code | Message | Description |
|---|---|---|
| 500 | Đã có lỗi xảy ra! | Đã xảy ra lỗi trong quá trình thực thi. |
| 405 | Phương thức không hợp lệ | Phương thức HTTP không hợp lệ. |
| 500 | Hệ thống đang sự cố | Đã xảy ra lỗi trong quá trình thực thi. |
| 404 | Đường dẫn không tồn tại, vui lòng thử lại sau | Không tìm thấy tài nguyên hoặc trang được yêu cầu. |
| 405 | Yêu cầu không hợp lệ | Phương thức không được phép. |
| 500 | Internal Server Error | Yêu cầu không được hoàn thành do lỗi nội bộ từ phía máy chủ. |
| 503 | Service Unavailable | Máy chủ tạm thời không khả dụng. |
2. Lỗi xác thực
| HTTP Code | Message | Description |
|---|---|---|
| 401 | Cần cung cấp token hợp lệ | Invalid token |
3. Lỗi với API tạo đơn hàng
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 400 | 4010101 | Thiếu thông tin địa chỉ | Trường pickup hoặc delivery bị thiếu thông tin trong phần thân (body) của request. |
| 400 | 4010102 | Vui lòng nhập địa chỉ chi tiết lấy hàng | Trường pickup.address bị thiếu thông tin trong phần thân (body) của request. |
| 400 | 4010103 | Vui lòng nhập địa chỉ chi tiết giao hàng | Trường delivery.address bị thiếu thông tin trong phần thân (body) của request. |
| 400 | 4010104 | Vui lòng nhập tỉnh lấy hàng | Trường pickup.province bị thiếu thông tin trong phần thân (body) của request. |
| 400 | 4010105 | Vui lòng nhập tỉnh giao hàng | Trường delivery.province bị thiếu thông tin trong phần thân (body) của request. |
| 400 | 4010106 | Vui lòng nhập phường/xã lấy hàng | Trường pickup.ward bị thiếu thông tin trong phần thân (body) của request. |
| 400 | 4010107 | Vui lòng nhập phường/xã giao hàng | Trường delivery.ward bị thiếu thông tin trong phần thân (body) của request. |
| 400 | 4010108 | Vui lòng nhập địa chỉ thôn/áp/xóm/tổ giao hàng | Trường delivery.hamlet bị thiếu thông tin trong phần thân (body) của request. |
| 400 | 4010109 | Thiếu thông tin địa chỉ cần phân tích | Không đủ thông tin địa chỉ lấy và giao trong request |
| 400 | 4010110 | Lỗi trong quá trình phân tích địa chỉ | Không phân tích được địa chỉ lấy/giao/trả |
| 400 | 4010111 | Thiếu thông tin đơn hàng | Thiếu thông tin trường order hoặc items hoặc pickup hoặc delivery trong request |
| 400 | 4010112 | Thiếu thông tin địa chỉ | Không đủ thông tin địa chỉ lấy và giao trong request |
| 400 | 4010113 | Thiếu thông tin địa chỉ trả hàng | Thiếu thông tin địa chỉ trả hàng trong request |
| 400 | 4010114 | Vui lòng nhập mã đơn hàng | Trường order.partner_id bị thiếu thông tin trong phần thân (body) của request |
| 400 | 4010115 | Vui lòng nhập loại dịch vụ | Trường order.service_type bị thiếu thông tin trong phần thân (body) của request |
| 400 | 4010116 | Vui lòng nhập số tiền COD | Trường order.cod_amount bị thiếu thông tin trong phần thân (body) của request |
| 400 | 4010117 | Vui lòng nhập đơn vị khối lượng | Trường order.weight_option bị thiếu thông tin trong phần thân (body) của request |
| 400 | 4010118 | Đã tồn tại đơn hàng với id [order-id] | Đã tồn tại đơn hàng với order.partner_id trong request |
| 400 | 4010119 | Địa chỉ lấy cần có tọa độ (lat, lng) đối với dịch vụ hỏa tốc | Không lấy được tọa độ địa chỉ lấy (đối với request đăng đơn dịch vụ hỏa tốc) |
| 400 | 4010120 | Địa chỉ giao cần có tọa độ (lat, lng) đối với dịch vụ hỏa tốc | Không lấy được tọa độ địa chỉ giao (đối với request đăng đơn dịch vụ hỏa tốc) |
4. Lỗi cho API xác nhận ready to ship
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 400 | 4010201 | Đơn hàng đã được xác nhận | Đơn hàng đã được xác nhận |
5. Lỗi cho API huỷ đơn hàng
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 400 | 4010301 | Đơn hàng đã ở trạng thái hủy | Đơn hàng đã bị hủy trước đó |
| 400 | 4010302 | Không tìm thấy vận đơn trên hệ thống | Không tìm thấy đơn hàng trong hệ thống |
6. Lỗi cho API tính phí và thời gian giao
Docs: https://oms-docs.ghtklab.com/orders/shipping-calculation#ph%E1%BA%A3n-h%E1%BB%93i
7. Lỗi cho API lấy trạng thái đơn hàng
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 500 | 5010401 | Có lỗi không mong muốn khi in đơn hàng, vui lòng thử lại yêu cầu này! | Đã xảy ra lỗi trong quá trình thực thi. |
8. Lỗi cho API in đơn hàng
| HTTP Code | Error Code | Message | Description |
|---|---|---|---|
| 500 | 5010501 | Có lỗi không mong muốn khi in đơn hàng, vui lòng thử lại yêu cầu này! | Đã xảy ra lỗi trong quá trình thực thi. |