API Hataları — Her Kodun Anlamı ve Nasıl Düzeltileceği

FastOG, bir istek başarısız olduğunda — imzalı bir OG görseli oluşturma veya ürün içi yönetim yüzeylerinden birine yapılan çağrı — makine tarafından okunabilir hata kodları döndürür. Her hata yanıtı şunları içerir:

• error — eski kısa belirteç. Eski bir istemcinin çalışmaya devam etmesi için her hatada hâlâ mevcuttur.
• code — aynı kararlı, belgelenmiş hata kodu (aşağıdaki tablo), genel API'nin kullandığı ad altında.
• message — neyin yanlış gittiğine dair tek cümlelik bir açıklama.
• hint — neyin yanlış gittiğine ve nasıl düzeltileceğine dair kısa, sade bir açıklama.
• docs_url — bu sayfaya, o kodun bölümüne sabitlenmiş bir bağlantı.
• request_id — bu HTTP hatasını dashboard'daki Render Logs tablosundaki bir satırla ilişkilendirir (X-Request-ID yanıt başlığında da döndürülür). İlişkilendirilecek bir şeyi olmayan bir yüzey null yanıtlar, ancak anahtar her zaman mevcuttur.

Ürün içi yüzeyler — Shopify yönetim paneli, WooCommerce Studio, Wix köprüsü ve demo — aşağıdaki kodlar için aynı zarfı yanıtlar, böylece bir hata nerede karşılaşırsanız karşılaşın aynı anlama gelir. Bir modül yüzeyi, bir kod için her zaman döndürdüğü HTTP durumunu koruyabilir (örneğin render_failed kapak dışa aktarımında 503, genel API'de 502 yanıtlar); kod, mesaj, ipucu ve belge bağlantısı değişmez.

Hata yanıtını okuma

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

Anlamadığınız bir yanıt alırsanız, en hızlı yol şudur:

1. code değerini not edin.
2. URL oluşturucunuzu kontrol edin — hataların çoğu hesap sorunları değil, imzalama hatalarıdır.
3. Tam nedeni ve çözümü için aşağıdaki kodla eşleştirin.
4. Dashboard'da Render Logs bölümünü açın ve aynı error_code ile filtreleyin — her satır istenen parametreleri gösterir, böylece yeniden üretebilir (ve request_id değerinin eşleştiğini doğrulayabilirsiniz).

İmzalama ve kimlik doğrulama

missing_signature

İsteğinizde key ve/veya s (imza) sorgu parametreleri eksik.

Düzeltme: URL'nizin hem key=<api-key> hem de s=<hmac-signature> içerdiğinden emin olun. Oluşturmak için SDK'yı veya /docs/hmac-signature-guide adım adım kılavuzunu kullanın.

invalid_signature

s değeri, HMAC gizli anahtarınızın bu URL için ürettiği değerle eşleşmedi.

Düzeltme: imza, s hariç tüm sorgu parametrelerini kapsar ve anahtarlar sıralanır. Herhangi bir parametreyi değiştirmek — sıralamayı değiştirmek, URL kodlama farklılıkları veya boşluk eklemek dahil — imzayı geçersiz kılar. Her değişiklikten sonra yeniden imzalayın. Gizli anahtarınızın, API anahtarı oluşturulduğunda gösterilenle aynı olduğunu doğrulayın.

invalid_signature_format

s değeri 64 karakterlik bir hex dizesi değil.

Düzeltme: imza ham SHA-256 hex (küçük harf a-f0-9) olmalıdır. Çıktıyı base64 ile kodluyorsanız veya kısaltıyorsanız, düz hex kullanın.

expired_timestamp

Sağladığınız t zaman damgası 5 dakikadan daha eski.

Düzeltme: her URL oluşturduğunuzda zaman damgasını yeniden üretin. Bu kod eski imzalı URL akışı için geçerlidir; güncel HMAC v2 akışında zaman damgası yoktur.

invalid_api_key

Geçirdiğiniz key mevcut değil.

Düzeltme: tam API anahtarını dashboard'dan kopyalayın — bu, sk_ ile başlayan genel tanımlayıcıdır. Geneldir ve URL'lerde güvenlidir; sahipliği kanıtlayan şey gizli anahtardır (asla URL'lerde yer almaz).

missing_hmac_secret

API anahtarı için yapılandırılmış bir HMAC gizli anahtarı yok.

Düzeltme: dashboard'da yeni bir API anahtarı oluşturun — HMAC gizli anahtarı oluşturma sırasında üretilir ve bir kez gösterilir.

Parametre / girdi

invalid_image_url

URL taşıyan bir prop (image, brand_logo, logo, avatar, background_image, ...) herkese açık bir http(s) URL'si değil.

Düzeltme: herkese açık şekilde getirilebilen bir https://... URL'si geçirin. Sunucu tarafı istek sahteciliğini (SSRF) önlemek için localhost, özel IP'ler ve çıplak yollar reddedilir.

Abonelik

subscription_required (402)

İstek Dynamic API'ye ulaştı ancak hesabınızın etkin bir planı yok. API erişimi yalnızca abonelikle mümkündür: plan bir ön koşuldur ve FastOG uygulamalarının sunduğu kapsam + yetenek basamaklarının aynısını içerir. Render işlemlerinin kendisi ölçülmez — aylık render kotası ve aşım faturalandırması yoktur.

Çözüm: dashboard üzerinden bir Dynamic API planı seçin ve bir API anahtarı oluşturun. Yanıt, planlar sayfasına işaret eden bir top_up_url içerir.

Render hizmeti

store_blocked (403)

Bu anahtarın arkasındaki mağaza için render işlemi FastOG tarafından duraklatıldı (örneğin kötüye kullanım veya kontrolsüz kullanım). Edge'de önceden önbelleğe alınmış kapaklar, süreleri dolana kadar sunulmaya devam edebilir. Çözmek için destek ekibiyle iletişime geçin; istekte değiştirebileceğiniz hiçbir şey bunu düzeltmez.

render_unreachable

Render hizmetine ulaşılamadı (kısa yeniden başlatma aralığı).

Çözüm: birkaç saniye içinde yeniden deneyin. Bu deneme için render sayılmadı.

render_failed

Render hizmeti isteğiniz için bir hata döndürdü.

Çözüm: şablon prop'larınızı doğrulayın — uzun/hatalı biçimli değerler, desteklenmeyen alanlar veya erişilemeyen bir upstream görseli. Yanıt, altında yatan status bilgisini içerir. Render sayılmadı.

Mağaza yönetici yüzeyleri

Bu kodlar, Shopify yöneticisinden ve WooCommerce Studio'dan yanıt verir — imzalı API yerine satıcının içinde çalıştığı gömülü düzenleyicilerden. Birkaçı genel API ile paylaşılır (invalid_image_url, render_failed, invalid_signature); bunlar yukarıda belgelenen girişi korur.

Wix köprüsü

Wix köprüsü, satıcı oturumuyla değil Wix uygulamasıyla imzalandığından, hataları uygulama geliştiricisine yöneliktir. Her yanıt yine de code ve request_id taşır; köprü istek kimliği, imzalı zarftaki kimliktir.

Demo yüzeyi

Demo, satıcı uç noktası değil, yalnızca sahibine açık satış konsoludur.

Kapsamlı kural düzenleyici kodları

Kapsamlı kural düzenleyicileri (Shopify yönetim paneli ve WooCommerce Studio) bu belirteçleri satıcının kendi diline kendileri çevirir; bu nedenle yanıtları error ve code içerir ancak hint içermez — ikinci bir İngilizce açıklama, satıcının gerçekte gördüğü yerelleştirilmiş açıklamadan yalnızca sapma gösterir:

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.

Hâlâ takıldınız mı?

• Dashboard'daki Render Logs sayfasını açın — her sonuç (başarı + reddetme) kendi error_code değeri, HTTP durum kodu ve istenen parametrelerle birlikte listelenir.
• İmzalı bir URL üzerinde php artisan og:diagnose çalıştırarak tüm işlem hattını adım adım izleyin ve hangi aşamanın başarısız olduğunu görün.
• Kullandığınız framework için kenar çubuğundaki belgelere göz atın (Next.js, Express, SvelteKit, ...).