Mã lỗi CPP_*
Từ vựng lỗi & trạng thái publish dùng chung giữa Citely và receiver.
Receiver không trả lỗi tự do. Trả mã chuẩn để Citely map thẳng vào error-catalog của nó và hiện đúng cách xử lý cho user — thay vì một "500 Internal Error" mù mờ.
Response lỗi: mã HTTP + JSON { "error": "<CODE>", "message": "mô tả ngắn" }.
Mã lỗi receiver → Citely
| HTTP | error code | Khi nào | Citely xử lý / hiện cho user |
|---|---|---|---|
| 401 | CPP_SIG_INVALID | HMAC không khớp | "Secret lệch giữa Citely và site → xoay lại secret & cập nhật env." |
| 401 | CPP_REPLAY | abs(now - ts) > 300s | "Đồng hồ server site lệch > 5 phút → chỉnh NTP." |
| 400 | CPP_VERSION_UNSUPPORTED | Site chưa hỗ trợ version/protocol này | "Site cần nâng cấp receiver lên CPP v1." Citely chặn publish. |
| 422 | CPP_VALIDATION | Payload thiếu/sai field bắt buộc (kèm field) | Hiện đúng field lỗi (vd title vượt giới hạn Zod của site). |
| 409 | CPP_CONFLICT | Slug/externalId đụng bản ghi khác | "Trùng bài — kiểm tra externalId/slug." |
| 429 | CPP_RATE_LIMITED | Site tự giới hạn tần suất | Citely backoff & retry. |
| 500 | CPP_STORAGE_FAILED | Ghi thất bại (DB write / file) | "Lỗi phía site khi lưu bài." Citely retry. |
| 502 | CPP_UNREACHABLE | Không kết nối được endpoint (timeout, DNS, WAF chặn) | "Không gọi được site — kiểm firewall/WAF/allowlist IP Citely." |
Quy ước: mọi mã bắt đầu CPP_, SCREAMING_SNAKE, không đổi tên khi đã phát hành (thêm
mã mới nếu cần nghĩa mới). Với CPP_VALIDATION, kèm "field" để Citely chỉ đúng chỗ:
{ "error": "CPP_VALIDATION", "message": "title too long (max 70)", "field": "title" }Trạng thái publish (status trong echo)
status | Nghĩa | Adapter điển hình |
|---|---|---|
live | Bài đã hiển thị công khai tại url | db (render động) |
building | Đã nhận & lưu, đang chờ CI/build để hiển thị | fs-build |
Chi tiết vòng đời building → live: Trạng thái bất đồng bộ.
Đối xứng hai chiều
Citely dùng bộ mã này ở cả hai chiều: khi transport gặp lỗi lúc POST tới site, nó phân
loại về đúng CPP_* và surface qua hệ lỗi của Citely. Cùng một ngôn ngữ lỗi từ Citely → site
→ về Citely, nên user luôn thấy thông điệp hành động được, không phải log thô.