Xử lý sự cố
Lỗi thường gặp và cách tự xử lý trước khi liên hệ support.
Xử lý sự cố
Tổng hợp lỗi tenant hay gặp, cách tự kiểm tra và khi nào cần tạo Support ticket.
Upload & Documents
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
Failed sau upload | File >10MB, MIME không hỗ trợ, parse lỗi | Kiểm tra size & định dạng, bấm Retry Ingestion. Nếu vẫn fail, thử file khác. |
Ready mãi không lên | Ingestion đang chunk/embed | Đợi 1-2 phút, refresh. Nếu >10 phút vẫn processing, retry. |
| Không thấy tài liệu trong Job | Tài liệu Archived hoặc khác org | Kiểm tra filter status trong Documents, đảm bảo không archived. |
Publishers & Xuất bản
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
Test Connection báo failed | Sai URL/credentials, firewall chặn | Kiểm tra lại siteUrl, username/appPassword (WP), adminUrl/apiKey (Ghost). Thử Test Connection lại. |
| Verification hết hạn | Quá 30 ngày chưa test | Vào Publishers → bấm Test lại để refresh lastTestedAt. |
publish_failed | Credentials hết hạn, API platform lỗi, publisher_attempts.error | Xem history của publisher, đọc error + statusCode. Thử verifyPublishedArticle. Nếu 401/403 → rotate credentials. |
Approve bị chặn | Ảnh chưa confirm rights | Vào Media → confirmRightsForDraft cho draft đó. |
Không xóa publisher khi còn draft/job đang tham chiếu — hệ thống chặn delete. Hãy unlink job trước.
Jobs & Calendar
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
Job error | Cron sai, lastError có chi tiết | Xem getById → lastError, sửa cronExpression hoặc scheduledDates. |
| Calendar trống | Filter attention hoặc sai tháng | Đổi ?month= hoặc filter status=all, kiểm tra schedulingConfig. |
| Trigger không chạy | Quota hết, job paused | Kiểm tra Credits balance, resume job nếu paused. |
next_run_at không đúng | Đổi timezone tenant | Hệ thống tự reconcile — đợi 1 phút hoặc kiểm tra schedulingConfig.timezone. |
SEO & GSC
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
GSC state mismatch / CSRF | Callback bị can thiệp hoặc hết hạn | Thử connect lại từ /dashboard/seo → lấy getGscAuthUrl mới. |
No GSC data | Chưa confirmGscProperty hoặc chưa sync | listGscSites → confirmGscProperty (admin), rồi getSearchAnalytics. |
Audit failed | Site block crawler, timeout | retryAudit hoặc cancelAudit rồi runFullAudit lại. Kiểm tra robots.txt. |
Readiness blocked | Thiếu GSC/audit/recommendations | Vào SEO Overview → bổ sung scan/audit trước khi generateDraft Monthly Plan. |
Credits & Billing
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
Quota exceeded / 429 | Vượt hard cap | Vào /dashboard/credits xem balance, vào /dashboard/billing → createPortalSession để nâng gói hoặc createCheckoutSession nạp thêm. |
reserve fail | Balance không đủ | Nạp credit trước khi tạo job/chat hàng loạt. quote trước để ước lượng. |
| Subscription không sync | Stripe webhook chưa tới | Đợi 2-3 phút, refresh Billing. Nếu vẫn sai, tạo Support ticket. |
Chat & Media
| Lỗi | Nguyên nhân | Cách xử lý |
|---|---|---|
| Ảnh không hiện trong history | Signed URL hết hạn | Hệ thống tự stale-image recovery — refresh trang. Nếu vẫn không hiện, regenerateImage. |
generateDraft báo quota | Hết websearch quota hoặc credits | Kiểm tra getWebsearchQuota và credits.balance. |
| Conversation mất | Đã deleteConversation | Không khôi phục được — cân nhắc trước khi xóa. |
Activity Log & Support
- Không thấy log → kiểm tra filter
type/dateRange, thửexportCsvđể xem đầy đủ - Ticket không phản hồi → kiểm tra
notificationscósupport.replykhông, thửaddMessageđể bump - Cần hỗ trợ nhanh → tạo ticket với
subjectrõ ràng +messagemô tả steps đã thử
Khi nào tạo Support ticket
Tạo ticket tại /dashboard/support khi:
- Đã thử các bước trên nhưng vẫn lỗi
- Lỗi 5xx/500,
INTERNAL_SERVER_ERRORkhi gọi bất kỳ API nào - Cần admin thao tác (approve plan, configure rescan, confirm GSC property)
Ghi rõ: org slug, URL, thời gian, steps to reproduce, screenshot nếu có.
Mọi lỗi đều được log với requestId — đính kèm khi tạo ticket để admin tra nhanh trong admin/traces.