Giới hạn, phản hồi & mã lỗi

Mặc định mỗi API key được 60 request trong mỗi phút (cửa sổ cố định theo phút). Vượt giới hạn nhận 429 RATE_LIMIT_001; đợi số giây trong header Retry-After rồi gọi lại. Cần giới hạn cao hơn: liên hệ GoHost.

Rate limit

Mọi phản hồi đã qua bước xác thực đều có ba header (lỗi 401 thì không có):

Header	Nghĩa
X-RateLimit-Limit	Số request tối đa mỗi phút của key
X-RateLimit-Remaining	Số request còn lại trong phút hiện tại
X-RateLimit-Reset	Thời điểm (Unix timestamp) chắc chắn được gọi lại — có thể muộn hơn đầu phút kế tiếp

Khi vượt, phản hồi 429 có thêm Retry-After và body gồm limit, remaining, reset_at, retry_after.

Cấu trúc phản hồi

Thành công, một bản ghi:

{ "success": true, "data": { "id": "…", "…": "…" } }

Trường id là mã của bản ghi (ví dụ mã đặt phòng), không phải id nội bộ của GoHost.

Thành công, danh sách. Danh sách cơ sở, loại phòng, nguồn đặt, dịch vụ… trả data là mảng, không phân trang. Riêng danh sách đặt phòng và lịch sử gửi webhook có thêm pagination:

{
  "success": true,
  "data": [ { "id": "…" } ],
  "pagination": {
    "current_page": 1, "per_page": 10, "total": 42, "last_page": 5,
    "from": 1, "to": 10,
    "links": { "first": "…", "last": "…", "prev": null, "next": "…" }
  }
}

Tham số phân trang: page, per_page (mặc định 10). Riêng Get Bookings: bắt buộc start_date và end_date (lọc theo ngày nhận phòng, tối đa 30 ngày), per_page từ 1 đến 50.

Lỗi (một số lỗi 500 khi tạo / xác nhận / thêm thanh toán / huỷ đơn chỉ có message, không có error_code):

{ "success": false, "message": "…", "error_code": "AUTH_002" }

Lỗi dữ liệu đầu vào trả 422, message là lỗi đầu tiên, errors liệt kê lỗi theo từng trường:

{ "success": false, "message": "…", "errors": { "checkout_date": ["…"] } }

Dữ liệu được cache

Một số endpoint đọc trả kết quả cache, nên thay đổi trên GoHost có thể chậm vài phút mới thấy qua API:

Endpoint	Cache
Danh sách cơ sở	5 phút
Tìm cơ sở còn phòng	1 phút
Quốc gia, tỉnh/thành, phường/xã	7 ngày
Nguồn đặt, phương thức thanh toán, dịch vụ	10 phút
Loại phòng, tìm phòng trống, đặt phòng	Không cache

Bảng mã lỗi

Mã	HTTP	Nghĩa	Cách xử lý
AUTH_001	401	Thiếu header Authorization hoặc sai định dạng	Gửi Bearer {api_key}:{api_secret}
AUTH_002	401	Sai key/secret, key đã bị tắt hoặc hết hạn	Kiểm lại secret; liên hệ GoHost nếu key bị tắt
AUTH_006	403	Key không có scope cần cho endpoint	Xem required_scope, xin GoHost thêm scope
RATE_LIMIT_001	429	Vượt giới hạn request mỗi phút (hoặc hệ thống đếm giới hạn tạm lỗi — request bị chặn để an toàn)	Đợi Retry-After giây
RATE_LIMIT_002, AUTH_005	500	Lỗi cấu hình phía GoHost	Báo GoHost kèm thời điểm gọi
TENANT_001–TENANT_004	4xx	tenant_id sai, không tồn tại, khác tổ chức, hoặc cơ sở tạm ngưng	Xem Xác thực & API key
TENANT_006	404	Không tìm thấy cơ sở	Kiểm tenant_id
BOOKING_001	400 / 500	Thao tác đặt phòng thất bại	Đọc message; 500 là lỗi bất ngờ — báo GoHost kèm thời điểm gọi
BOOKING_002	400	Dịch vụ không hợp lệ khi cập nhật đặt phòng (rooms[].services)	Lấy mã dịch vụ từ Get Services List
BOOKING_ROOM_INVALID_STATUS	422	Trạng thái phòng/đơn không cho phép thao tác (kèm checkin_status, booking_status)	Kiểm trạng thái trước khi gọi
BOOKING_CHECKOUT_UNBALANCED	422	Cơ sở yêu cầu thanh toán đủ trước khi trả phòng; kèm balance (> 0 còn nợ, < 0 trả thừa)	Thêm thanh toán rồi trả phòng
INVOICE_NO_PRIMARY_GUEST	422	Gửi thông tin hoá đơn khi đơn chưa có khách chính	Thêm khách chính trước
WEBHOOK_001	422	URL webhook không hợp lệ hoặc đã đăng ký	Xem Webhook
WEBHOOK_002	422	Tên sự kiện không hợp lệ	Dùng sự kiện trong bảng của bài Webhook
WEBHOOK_003	422	Đã đủ 5 endpoint đang bật	Tắt hoặc xoá bớt endpoint
WEBHOOK_004	404	Không tìm thấy endpoint	Kiểm code của endpoint
WEBHOOK_005	409	API key đã bị thu hồi, không bật lại endpoint được	Liên hệ GoHost
—	422	Dữ liệu đầu vào sai	Xem errors