Pilot Support Playbook

Xử lý sự cố khi hỗ trợ đối tác Pilot. Mỗi tình huống: Dấu hiệu · Nguyên nhân thường gặp · Cách kiểm tra · Khi nào mở Hotfix Sprint.
Nguyên tắc: chỉ mở Hotfix cho blocker (chặn luồng Availability→Booking→Confirm→Cancel và không có workaround). Còn lại → Issue Log Backlog.
Tham chiếu: Error Catalog · Integration Guide.

Nguyên tắc chung khi nhận báo lỗi

Luôn xin đối tác: endpoint · payload (ẩn PII) · x-request-id · HTTP status · error.code. KHÔNG nhận API key. Rẽ nhánh theo error.code, không theo message.

401 Unauthorized (UNAUTHENTICATED)

• Dấu hiệu: body JSON {"ok":false,"error":{"code":"UNAUTHENTICATED"}}, HTTP 401.
• Nguyên nhân thường gặp: thiếu/sai header x-bng-api-key; key bị revoke/hết hạn; Partner bị suspend/revoke (cổng Partner ở auth).
• Cách kiểm tra:
• npm run ops -- show-provisioning --customer <partnerId> --json → xem status key (active?) + lastUsedAt.
• Partner status: show-audit --partner <partnerId> (có partner.suspended/partner.revoked?).
• Đúng header chưa (chính tả x-bng-api-key).
• Khi nào Hotfix: Không (thường là cấu hình/lifecycle). Nếu key hợp lệ mà vẫn 401 (nghi lỗi resolver) → điều tra; chỉ Hotfix nếu tái hiện được lỗi hệ thống.

403 Forbidden

Hai loại — phân biệt theo body:

403a — nginx HTML "403 Forbidden" (KHÔNG phải JSON)

• Dấu hiệu: trang HTML nginx, không có error.code.
• Nguyên nhân: IP đối tác chưa allowlist trên staging (bị chặn trước app).
• Cách kiểm tra: curl -s -o /dev/null -w "%{http_code}" <BASE>/api/booking/availability?... từ IP đối tác → 403 HTML. /health vẫn 200.
• Khi nào Hotfix: Không — allowlist IP (thao tác ops, Runbook §3).

403b — JSON TENANT_INACTIVE hoặc TENANT_CONTEXT_MISMATCH

• Dấu hiệu: JSON error.code = TENANT_INACTIVE (tenant suspended/archived/provisioned) hoặc TENANT_CONTEXT_MISMATCH (client gửi tenantId sai).
• Cách kiểm tra: tenant-health --tenant <tenantId> → status. Nếu suspended/archived/provisioned ⇒ đúng thiết kế.
• Khi nào Hotfix: Không. TENANT_INACTIVE = trạng thái vận hành (reactivate nếu cần); TENANT_CONTEXT_MISMATCH = đối tác bỏ tenantId khỏi request.

404 Not Found

• Dấu hiệu: error.code = LISTING_UNIT_NOT_FOUND / RESERVATION_NOT_FOUND / PRICING_NOT_FOUND / NOT_FOUND.
• Nguyên nhân: unitId/reservationId sai hoặc thuộc tenant khác (cross-tenant cố ý trả 404); chưa seed inventory/giá; sai route.
• Cách kiểm tra: tenant-health --tenant <tenantId> (units > 0?); đối chiếu unitId với danh sách đã giao; kiểm route theo openapi.yaml.
• Khi nào Hotfix: Không (dữ liệu/route). PRICING_NOT_FOUND ở unit lẽ ra có giá ⇒ kiểm seed; vẫn không phải code fix.

409 Conflict

• Dấu hiệu: error.code = AVAILABILITY_NOT_AVAILABLE / RESERVATION_INVALID_STATUS_TRANSITION / RESERVATION_CAPACITY_EXCEEDED / LISTING_UNIT_INACTIVE / IDEMPOTENCY_KEY_CONFLICT / IDEMPOTENCY_IN_PROGRESS.
• Nguyên nhân: hết chỗ; thao tác lifecycle sai trạng thái; vượt sức chứa; reuse Idempotency-Key với body khác; request trước chưa xong.
• Cách kiểm tra: trạng thái đơn (show-audit --tenant / list reservations); logic idempotency của đối tác.
• Khi nào Hotfix: Không (đúng thiết kế). IDEMPOTENCY_IN_PROGRESS → đối tác backoff rồi thử lại.

5xx (INTERNAL, HTTP 500)

• Dấu hiệu: {"ok":false,"error":{"code":"INTERNAL","message":"Lỗi máy chủ nội bộ"}}, HTTP 500.
• Nguyên nhân: lỗi ngoài dự kiến phía server (không lộ chi tiết).
• Cách kiểm tra: log API (grep '"status":5' <api log>), npm run ops -- health, kiểm DB kết nối. Lấy x-request-id để truy vết.
• Khi nào Hotfix: CÓ, nếu tái hiện được và chặn luồng lõi ⇒ mở Hotfix Sprint (chỉ sửa blocker). Ghi [Issue Log] + [Decision Log]. Lưu ý: Gamma-1 ghi nhận 0 lỗi 5xx.

Timeout

• Dấu hiệu: client timeout, không nhận response.
• Nguyên nhân: mạng; API/DB quá tải; (staging) nginx.
• Cách kiểm tra: /health phản hồi? ops health? Độ trễ DB? Đối tác đã đặt timeout hợp lý + kèm Idempotency-Key khi tạo đơn (để retry không tạo trùng)?
• Khi nào Hotfix: Không trừ khi do lỗi server tái hiện (khi đó như 5xx). Hướng dẫn đối tác retry có backoff + Idempotency-Key.

Rate Limit

• Dấu hiệu: (hiện tại) chưa cưỡng chế ở gateway partner ⇒ đối tác không gặp 429 trong Pilot.
• Nguyên nhân: giới hạn chưa bật (demo-level). Tương lai sẽ trả 429 + Retry-After.
• Cách kiểm tra: nếu đối tác báo 429 (bất ngờ) → kiểm có lớp proxy nào của họ; phía BNG chưa phát 429 cho partner API.
• Khi nào Hotfix: Không. Khuyến nghị đối tác tự throttle + chuẩn bị xử lý 429 cho tương lai (Backlog: bật rate-limit + công bố ngưỡng).

Bảng quyết định nhanh: Hotfix hay không?

Mọi trường hợp mở Hotfix: ghi Issue Log (severity=Blocker) + Decision Log, và không mở rộng phạm vi ngoài blocker.