# Tìm và xử lý lỗi thường gặp

Kiểm tra lỗi render, dữ liệu không hiển thị, ảnh bị chặn và ngắt trang.

## Preview được nhưng render không chạy
Kiểm tra version đã published, đúng project/key, scope `template:render` và quota. Đọc cảnh báo ảnh/tài nguyên trong preview; preview có thể bỏ tài nguyên bị chặn trong khi render thật từ chối.

## Nhận diện lỗi trước khi thử lại

| Code hoặc hiện tượng | Cách xử lý |
| --- | --- |
| `PDF_TEMPLATE_VERSION_NOT_PUBLISHED` | Mở đúng version trong editor và Publish, sau đó gửi job mới. |
| `PDF_INVALID_API_KEY` / `PDF_API_KEY_INSUFFICIENT_SCOPE` | Kiểm tra key hiện hành, đúng project và scope `template:render`. |
| `PDF_RENDER_QUOTA_EXCEEDED` / `quota_exceeded` | Xem usage workspace ở Settings. Gửi POST liên tục không khôi phục quota. |
| `EXTERNAL_IMAGES_NOT_ALLOWED` | Đọc cảnh báo preview và [chính sách ảnh](/docs/vi/assets/images/); dùng tài nguyên mà gói hiện tại cho phép. |
| `ASSET_STORAGE_PLAN_REQUIRED` | Workspace hiện không có quyền phục vụ project assets. Kiểm tra gói và thông báo storage trong Assets. |
| `RENDER_TIMEOUT` | Giảm hoặc chia nội dung lớn, giảm việc tải ảnh và xem giới hạn xử lý trước khi thử lại. |
| 404 ngay sau render 202 | Giữ render ID đã nhận và [xem hướng dẫn retry status](/docs/vi/developers/render-reference/). |
| PDF vẫn hiện nhãn cũ | Save thiết kế rồi tạo lại PDF preview. Input trong Run không đổi dữ liệu preview của editor. |

## Dữ liệu không hiện
Kiểm tra tên parameter, binding `params`, scope props và variant đang chọn. Với array, kiểm tra đang đọc field của item trong vòng lặp. Mở payload mẫu để đối chiếu hình dạng JSON, không chỉ tên field ngoài cùng.

## Bảng bị cắt hoặc nhiều khoảng trắng
Kiểm tra CSS height/overflow, lề, font và cấu hình giữ section cùng nhau. Thử ít dữ liệu trước rồi tăng dần; xem PDF preview để biết vị trí tràn trang thực tế.

## Không tải được file
Kiểm tra job đã `success`, output còn trong thời gian lưu và key thuộc đúng project. Không coi đường download có thể gửi cho bất kỳ ai mà không có quyền.

## API báo 401/403
Kiểm tra API origin, header `ApiKey`, credential hiện hành và scopes. Key project A không dùng cho template project B. Không gửi key cho bên hỗ trợ; chỉ gửi ID tài nguyên và thông báo lỗi đã che dữ liệu.

## AI báo revision stale
Template đã có revision mới so với bản agent đang dùng. Đọc lại context và xây lại thay đổi, không ghi đè mù quáng. Với lỗi kết nối MCP, kiểm tra `/mcp` khác `/docs/mcp` và header của đúng server.

## Trước khi gửi hỗ trợ
Ghi lại thời điểm, thao tác, template/version, render ID hoặc delivery ID và lỗi cụ thể. Dùng dữ liệu giả để tái hiện nếu được. Che email, payload, API key và secret khỏi ảnh chụp.