Error API — Arti Setiap Kode dan Cara Memperbaikinya

FastOG mengembalikan kode error yang dapat dibaca mesin saat sebuah permintaan gagal — render OG image yang ditandatangani, atau panggilan ke salah satu permukaan admin di dalam produk. Setiap respons error menyertakan:

• error — token pendek lama. Tetap ada pada setiap kegagalan agar klien lama tetap berfungsi.
• code — kode error stabil dan terdokumentasi yang sama (tabel di bawah), dengan nama yang digunakan API publik.
• message — deskripsi satu kalimat tentang apa yang salah.
• hint — deskripsi singkat dalam bahasa sederhana tentang apa yang salah dan cara memperbaikinya.
• docs_url — tautan ke halaman ini, berjangkar pada bagian untuk kode tersebut.
• request_id — mengorelasikan kegagalan HTTP ini ke sebuah baris di tabel Render Logs pada dashboard (juga dikembalikan dalam header respons X-Request-ID). Permukaan yang tidak memiliki apa pun untuk dikorelasikan menjawab null, tetapi key tersebut selalu ada.

Permukaan di dalam produk — admin Shopify, WooCommerce Studio, jembatan Wix, dan demo — menjawab dengan envelope yang sama untuk kode-kode di bawah, sehingga sebuah kegagalan berarti hal yang sama di mana pun Anda menjumpainya. Permukaan modul dapat mempertahankan status HTTP yang selalu dikembalikannya untuk sebuah kode (misalnya render_failed menjawab 503 pada ekspor cover dan 502 pada API publik); kode, pesan, hint, dan tautan docs tidak berubah.

Membaca respons error

{
  "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-..."
}

Jika Anda menerima respons yang tidak dipahami, jalur tercepat adalah:

1. Catat code.
2. Periksa pembangun URL Anda — sebagian besar kegagalan adalah bug penandatanganan (signing), bukan masalah akun.
3. Cocokkan kode di bawah ini untuk penyebab dan perbaikan yang tepat.
4. Di dashboard, buka Render Logs dan filter dengan error_code yang sama — setiap baris menampilkan parameter yang diminta sehingga Anda dapat mereproduksi (dan memastikan request_id cocok).

Penandatanganan & autentikasi

missing_signature

Permintaan Anda tidak menyertakan parameter kueri key dan/atau s (signature).

Perbaikan: pastikan URL Anda menyertakan key=<api-key> dan s=<hmac-signature>. Gunakan SDK atau panduan /docs/hmac-signature-guide untuk membangunnya.

invalid_signature

Nilai s tidak cocok dengan yang dihasilkan oleh secret HMAC Anda untuk URL ini.

Perbaikan: signature mencakup setiap parameter kueri kecuali s, dengan kunci yang diurutkan. Mengubah parameter apa pun — termasuk mengubah urutan, perbedaan pengodean URL, atau menambahkan spasi — akan membatalkan signature. Tandatangani ulang setelah setiap perubahan. Pastikan secret Anda sama dengan yang ditampilkan saat API key dibuat.

invalid_signature_format

Nilai s bukan string hex 64 karakter.

Perbaikan: signature harus berupa hex SHA-256 mentah (huruf kecil a-f0-9). Jika Anda melakukan pengodean base64 atau memotong output, gunakan hex biasa.

expired_timestamp

Timestamp t yang Anda berikan sudah lebih dari 5 menit.

Perbaikan: buat ulang timestamp setiap kali Anda membangun URL. Kode ini berlaku untuk alur signed-URL lama; alur HMAC v2 saat ini tidak memiliki timestamp.

invalid_api_key

key yang Anda berikan tidak ada.

Perbaikan: salin API key lengkap dari dashboard — itu adalah pengenal publik yang dimulai dengan sk_. Ini bersifat publik dan aman digunakan di URL; secret (tidak pernah di URL) adalah yang membuktikan kepemilikan.

missing_hmac_secret

API key tidak memiliki secret HMAC yang dikonfigurasi.

Perbaikan: buat API key baru di dashboard — secret HMAC dibuat dan ditampilkan sekali saat pembuatan.

Parameter / input

invalid_image_url

Prop yang membawa URL (image, brand_logo, logo, avatar, background_image, ...) bukan URL http(s) publik.

Perbaikan: teruskan URL https://... yang dapat diambil secara publik. Localhost, IP privat, dan path tanpa domain ditolak untuk mencegah server-side request forgery.

Langganan

subscription_required (402)

Permintaan mencapai Dynamic API tetapi akun Anda tidak memiliki paket aktif. Akses API bersifat khusus langganan: paket adalah gerbangnya, dan paket tersebut membawa cakupan + tingkatan kemampuan yang sama dengan yang dijual aplikasi FastOG. Render itu sendiri tidak diukur — tidak ada kuota render bulanan dan tidak ada penagihan kelebihan.

Perbaikan: pilih paket Dynamic API di dasbor dan buat kunci API. Respons menyertakan top_up_url yang mengarah ke halaman paket.

Layanan render

store_blocked (403)

Render untuk toko di balik key ini telah dijeda oleh FastOG (misalnya penyalahgunaan atau penggunaan berlebihan). Cover yang sudah di-cache di edge dapat terus disajikan hingga kedaluwarsa. Hubungi support untuk menyelesaikannya; tidak ada yang dapat Anda ubah dalam permintaan yang akan memperbaiki ini.

render_unreachable

Layanan render tidak dapat dijangkau (jendela restart singkat).

Perbaikan: coba lagi dalam beberapa detik. Render tidak dihitung untuk percobaan ini.

render_failed

Layanan render mengembalikan error untuk permintaan Anda.

Perbaikan: verifikasi props template Anda — nilai yang terlalu panjang/malformed, field yang tidak didukung, atau gambar upstream yang tidak dapat dijangkau. Respons menyertakan status yang mendasarinya. Render tidak dihitung.

Permukaan admin toko

Kode-kode ini menjawab dari admin Shopify dan WooCommerce Studio — editor tertanam tempat merchant bekerja, bukan dari API yang ditandatangani. Beberapa di antaranya dipakai bersama dengan API publik (invalid_image_url, render_failed, invalid_signature); kode tersebut tetap memakai entri yang didokumentasikan di atas.

Bridge Wix

Bridge Wix ditandatangani oleh aplikasi Wix, bukan sesi merchant, sehingga kegagalannya ditujukan kepada pengembang aplikasi. Setiap respons tetap membawa code dan request_id; id permintaan bridge adalah id dari envelope yang ditandatangani.

Permukaan demo

Demo ini adalah konsol penjualan khusus pemilik, bukan endpoint merchant.

Kode editor aturan terbatas

Editor aturan terbatas (admin Shopify dan WooCommerce Studio) menerjemahkan token-token ini sendiri ke dalam bahasa merchant, sehingga responsnya membawa error dan code tetapi tidak membawa hint — deskripsi bahasa Inggris kedua hanya akan menyimpang dari versi terlokalisasi yang benar-benar dilihat merchant:

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.

Masih mengalami kendala?

• Buka halaman Render Logs di dashboard — setiap hasil (berhasil + ditolak) tercantum beserta error_code, status HTTP, dan parameter yang diminta.
• Jalankan php artisan og:diagnose pada URL yang sudah ditandatangani untuk menelusuri seluruh pipeline dan melihat tahap mana yang gagal.
• Periksa dokumentasi di sidebar untuk framework yang Anda gunakan (Next.js, Express, SvelteKit, ...).