Lỗi API — Ý nghĩa của từng mã và cách khắc phục

FastOG trả về các mã lỗi mà máy có thể đọc được khi một yêu cầu thất bại — một lần render OG image có ký, hoặc một lời gọi đến một trong các bề mặt quản trị trong sản phẩm. Mọi phản hồi lỗi đều bao gồm:

• error — token ngắn kế thừa. Vẫn xuất hiện trong mọi lần thất bại để client cũ tiếp tục hoạt động.
• code — cùng mã lỗi ổn định, được tài liệu hóa (bảng bên dưới), dưới tên mà API công khai sử dụng.
• message — mô tả một câu về những gì đã sai.
• hint — mô tả ngắn gọn bằng ngôn ngữ đơn giản về những gì đã sai và cách khắc phục.
• docs_url — liên kết đến trang này, neo tại phần dành cho mã đó.
• request_id — tương quan lỗi HTTP này với một dòng trong bảng Render Logs trên dashboard (cũng được trả về trong header phản hồi X-Request-ID). Một bề mặt không có gì để tương quan sẽ trả lời null, nhưng khóa này luôn hiện diện.

Các bề mặt trong sản phẩm — Shopify admin, WooCommerce Studio, Wix bridge và bản demo — trả lời với cùng cấu trúc phản hồi cho các mã bên dưới, vì vậy một lỗi có nghĩa giống nhau ở bất cứ nơi nào bạn gặp. Một bề mặt module có thể giữ nguyên mã trạng thái HTTP mà nó vẫn luôn trả về cho một mã (ví dụ render_failed trả lời 503 trên cover export và 502 trên API công khai); mã lỗi, thông điệp, gợi ý và liên kết tài liệu không thay đổi.

Đọc phản hồi lỗi

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

Nếu bạn nhận được phản hồi mà mình không hiểu, cách nhanh nhất là:

1. Ghi lại code.
2. Kiểm tra URL builder của bạn — phần lớn lỗi thất bại là do lỗi ký (signing), không phải vấn đề tài khoản.
3. Đối chiếu mã bên dưới để tìm nguyên nhân và cách khắc phục chính xác.
4. Trong dashboard, mở Render Logs và lọc theo cùng error_code — mỗi dòng hiển thị các tham số đã yêu cầu để bạn có thể tái tạo (và xác nhận request_id khớp).

Ký & xác thực

missing_signature

Yêu cầu của bạn thiếu tham số truy vấn key và/hoặc s (chữ ký).

Cách khắc phục: đảm bảo URL của bạn bao gồm cả key=<api-key> và s=<hmac-signature>. Sử dụng SDK hoặc hướng dẫn /docs/hmac-signature-guide để tạo URL.

invalid_signature

Giá trị s không khớp với giá trị mà HMAC secret của bạn tạo ra cho URL này.

Cách khắc phục: chữ ký bao phủ mọi tham số truy vấn ngoại trừ s, với các khóa được sắp xếp. Thay đổi bất kỳ tham số nào — bao gồm sắp xếp lại thứ tự, khác biệt về URL-encoding, hoặc thêm khoảng trắng — đều làm mất hiệu lực chữ ký. Ký lại sau mỗi lần thay đổi. Xác nhận rằng secret của bạn là secret được hiển thị khi tạo API key.

invalid_signature_format

Giá trị s không phải là chuỗi hex 64 ký tự.

Cách khắc phục: chữ ký phải là SHA-256 hex thô (chữ thường a-f0-9). Nếu bạn đang base64-encoding hoặc cắt ngắn kết quả, hãy dùng hex thuần.

expired_timestamp

Dấu thời gian t bạn cung cấp đã cũ hơn 5 phút.

Cách khắc phục: tạo lại dấu thời gian mỗi lần bạn tạo URL. Mã này áp dụng cho luồng signed-URL cũ; luồng HMAC v2 hiện tại không có dấu thời gian.

invalid_api_key

key bạn truyền vào không tồn tại.

Cách khắc phục: sao chép toàn bộ API key từ dashboard — đó là định danh công khai bắt đầu bằng sk_. Nó là công khai và an toàn trong URL; secret (không bao giờ đặt trong URL) mới là thứ chứng minh quyền sở hữu.

missing_hmac_secret

API key chưa được cấu hình HMAC secret.

Cách khắc phục: tạo một API key mới trong dashboard — HMAC secret được tạo và hiển thị một lần duy nhất khi tạo.

Tham số / đầu vào

invalid_image_url

Một prop chứa URL (image, brand_logo, logo, avatar, background_image, ...) không phải là URL http(s) công khai.

Cách khắc phục: truyền một URL https://... có thể truy xuất công khai. Localhost, IP riêng và đường dẫn trần bị từ chối để ngăn chặn server-side request forgery.

Gói đăng ký

subscription_required (402)

Yêu cầu đã đến Dynamic API nhưng tài khoản của bạn không có gói nào đang hoạt động. Quyền truy cập API là chỉ dành cho gói đăng ký: gói là điều kiện bắt buộc, và nó mang theo cùng mức độ phủ + thang năng lực mà các ứng dụng FastOG bán. Bản thân các lần render không bị tính phí theo lượt — không có hạn mức render hàng tháng và không có tính phí vượt mức.

Cách khắc phục: chọn một gói Dynamic API trong dashboard và tạo một API key. Phản hồi bao gồm một top_up_url trỏ đến trang các gói.

Dịch vụ render

store_blocked (403)

Tính năng render cho cửa hàng gắn với key này đã bị FastOG tạm dừng (ví dụ do lạm dụng hoặc sử dụng quá mức). Các ảnh bìa đã được cache tại edge vẫn có thể tiếp tục được phục vụ cho đến khi hết hạn. Hãy liên hệ bộ phận hỗ trợ để giải quyết; không có thay đổi nào trong request có thể khắc phục được vấn đề này.

render_unreachable

Không thể kết nối tới dịch vụ render (khoảng thời gian khởi động lại ngắn).

Cách khắc phục: thử lại sau vài giây. Lần render này không bị tính cho lần thử này.

render_failed

Dịch vụ render trả về lỗi cho request của bạn.

Cách khắc phục: kiểm tra các template props — giá trị quá dài/sai định dạng, trường không được hỗ trợ, hoặc ảnh upstream không thể truy cập. Phản hồi bao gồm status gốc. Lần render này không bị tính.

Bề mặt quản trị cửa hàng

Các mã này phản hồi từ Shopify admin và WooCommerce Studio — những trình soạn thảo nhúng mà người bán hàng làm việc trong đó thay vì API đã ký. Một số mã được dùng chung với API công khai (invalid_image_url, render_failed, invalid_signature); những mã đó giữ nguyên mục đã được ghi tài liệu ở trên.

Cầu nối Wix

Cầu nối Wix được ký bởi ứng dụng Wix chứ không phải phiên của người bán, vì vậy các lỗi của nó được gửi tới nhà phát triển ứng dụng. Mọi phản hồi vẫn mang code và request_id; id yêu cầu của cầu nối là id từ phong bì đã ký.

Bề mặt demo

Demo là bảng điều khiển bán hàng chỉ dành cho chủ sở hữu, không phải endpoint dành cho người bán.

Mã của trình soạn thảo quy tắc theo phạm vi

Các trình soạn thảo quy tắc theo phạm vi (Shopify admin và WooCommerce Studio) tự dịch các token này sang ngôn ngữ của chính người bán, vì vậy phản hồi của chúng chứa error và code nhưng không có hint — một mô tả tiếng Anh thứ hai sẽ chỉ lệch khỏi bản đã bản địa hóa mà người bán thực sự nhìn thấy:

scope_already_defined, scoped_rule_limit_reached, scoped_rules_not_on_plan, scope_value_required, scope_value_too_long, unknown_scope_type, base_rule_required, scoped_rules_product_only, cannot_delete_base_rule.

Vẫn chưa giải quyết được?

• Mở trang Render Logs trong dashboard — mọi kết quả (thành công + bị từ chối) đều được liệt kê kèm error_code, trạng thái HTTP và các tham số được yêu cầu.
• Chạy php artisan og:diagnose trên một URL đã ký để đi qua toàn bộ pipeline và xem giai đoạn nào thất bại.
• Xem tài liệu ở thanh bên cho framework bạn đang dùng (Next.js, Express, SvelteKit, ...).