Hướng dẫn
Quy ước và mã lỗi
Định dạng tiền, thời gian, số điện thoại, ngôn ngữ và bảng mã lỗi.
Dữ liệu
| Loại | Quy ước | Ví dụ |
|---|---|---|
| Tiền | Số nguyên, đơn vị đồng (VND) | 385000 = 385.000 đ |
| Thời gian | ISO 8601 có múi giờ | 2026-11-12T19:30:00+07:00 |
| Số điện thoại | Di động Việt Nam | 0912345678 hoặc +84912345678 |
| Khoảng cách | Mét, số nguyên | distance_m: 2417 |
| Thời lượng | Giây, số nguyên | duration_s: 409 |
| Body | JSON UTF-8 | Content-Type: application/json |
Ngôn ngữ
Header x-language: vi (mặc định) hoặc en chọn ngôn ngữ của error.message và tên dịch vụ.
Định dạng response
Thành công:
{ "success": true, "data": { } }Lỗi:
{
"success": false,
"error": {
"code": "invalid_request",
"message": "customer.phone must be a Vietnamese mobile number",
"details": [{ "field": "customer.phone", "message": "customer.phone must be a Vietnamese mobile number" }]
}
}Xử lý theo error.code, không theo message (message có thể đổi câu chữ).
Mã lỗi
| HTTP | code | Khi nào | Nên làm |
|---|---|---|---|
| 400 | invalid_request | Thiếu trường hoặc sai định dạng; xem details | Sửa request |
| 401 | invalid_api_key | Sai, thiếu, đã thu hồi key hoặc sai môi trường | Kiểm tra key |
| 403 | service_not_allowed | Dịch vụ hoặc hình thức thanh toán chưa mở cho tài khoản | Liên hệ GOCheap |
| 404 | not_found | Chuyến hoặc webhook không thuộc tài khoản | Kiểm tra mã |
| 409 | duplicate_reference | partner_reference_id đã dùng cho chuyến khác | Dùng mã khác hoặc tra chuyến cũ |
| 410 | quote_expired | Báo giá quá 10 phút hoặc đã dùng | Báo giá lại |
| 422 | address_not_found | Không xác định được địa chỉ | Ghi rõ phường/xã, tỉnh/thành |
| 422 | area_not_supported | Khu vực hoặc tuyến chưa có trong bảng giá | Báo khách chưa hỗ trợ |
| 422 | cannot_cancel | Chuyến đã đón khách hoặc đã kết thúc | Liên hệ tổng đài GOCheap |
| 429 | rate_limited | Vượt giới hạn request | Chờ theo Retry-After |
| 500 | internal_error | Lỗi phía GOCheap | Thử lại sau, giữ nguyên Idempotency-Key |