أخطاء API — ماذا يعني كل رمز وكيفية إصلاحه

يعيد FastOG رموز أخطاء قابلة للقراءة آليًا عند فشل الطلب — سواء كان طلب عرض صورة OG موقّعًا، أو استدعاءً لأحد واجهات الإدارة داخل المنتج. تتضمن كل استجابة خطأ ما يلي:

• error — الرمز القصير القديم. لا يزال حاضرًا في كل فشل حتى يستمر العميل الأقدم في العمل.
• code — رمز الخطأ نفسه المستقر والموثّق (الجدول أدناه)، تحت الاسم الذي تستخدمه واجهة API العامة.
• message — وصف من جملة واحدة لما حدث خطأ.
• hint — وصف قصير بلغة واضحة لما حدث خطأ وكيفية إصلاحه.
• docs_url — رابط إلى هذه الصفحة، مثبّت عند القسم الخاص بذلك الرمز.
• request_id — يربط فشل HTTP هذا بصف في جدول Render Logs في لوحة التحكم (يُعاد أيضًا في ترويسة استجابة X-Request-ID). الواجهة التي لا يوجد لديها ما تربطه تُرجع null، لكن المفتاح حاضر دائمًا.

تُرجع الواجهات داخل المنتج — لوحة إدارة Shopify، وWooCommerce Studio، وجسر Wix، والعرض التجريبي — نفس المغلّف للرموز أدناه، لذا يعني الفشل الشيء نفسه أينما واجهته. قد تحتفظ واجهة وحدة ما بحالة HTTP التي كانت تُرجعها دائمًا لرمز ما (على سبيل المثال render_failed تُرجع 503 عند تصدير الغلاف و502 عند واجهة API العامة)؛ أما الرمز والرسالة والتلميح ورابط الوثائق فلا تتغير.

قراءة استجابة الخطأ

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

إذا تلقيت استجابة لا تفهمها، فأسرع مسار هو:

1. سجّل code.
2. تحقّق من أداة بناء URL لديك — معظم حالات الفشل ناتجة عن أخطاء في التوقيع، لا عن مشكلات في الحساب.
3. طابِق الرمز أدناه لمعرفة السبب الدقيق والإصلاح.
4. في لوحة التحكم، افتح Render Logs وصفِّ حسب error_code نفسه — يعرض كل صف المعاملات المطلوبة حتى تتمكن من إعادة الإنتاج (والتأكد من تطابق request_id).

التوقيع والمصادقة

missing_signature

يفتقد طلبك إلى معاملات الاستعلام key و/أو s (التوقيع).

الإصلاح: تأكد من أن عنوان URL الخاص بك يتضمن كلاً من key=<api-key> وs=<hmac-signature>. استخدم SDK أو دليل /docs/hmac-signature-guide لبنائه.

invalid_signature

لم تتطابق قيمة s مع ما ينتجه سر HMAC الخاص بك لعنوان URL هذا.

الإصلاح: يغطي التوقيع كل معاملات الاستعلام باستثناء s، مع ترتيب المفاتيح. أي تغيير في أي معامل — بما في ذلك إعادة الترتيب أو اختلافات ترميز URL أو إضافة مسافات — يُبطل التوقيع. أعد التوقيع بعد كل تغيير. تأكد من أن سرك هو نفسه المعروض عند إنشاء مفتاح API.

invalid_signature_format

قيمة s ليست سلسلة hex من 64 حرفًا.

الإصلاح: يجب أن يكون التوقيع بصيغة SHA-256 hex خام (أحرف صغيرة a-f0-9). إذا كنت تستخدم ترميز base64 أو تقتطع الناتج، فاستخدم hex العادي.

expired_timestamp

الطابع الزمني t الذي قدمته أقدم من 5 دقائق.

الإصلاح: أعد توليد الطابع الزمني في كل مرة تبني فيها عنوان URL. ينطبق هذا الرمز على تدفق عنوان URL الموقّع القديم؛ أما تدفق HMAC v2 الحالي فلا يحتوي على طابع زمني.

invalid_api_key

مفتاح key الذي مررته غير موجود.

الإصلاح: انسخ مفتاح API الكامل من لوحة التحكم — فهو المعرّف العام الذي يبدأ بـ sk_. إنه عام وآمن في عناوين URL؛ أما السر (الذي لا يظهر أبدًا في عناوين URL) فهو ما يثبت الملكية.

missing_hmac_secret

لا يحتوي مفتاح API على سر HMAC مُهيأ.

الإصلاح: أنشئ مفتاح API جديدًا في لوحة التحكم — يُولَّد سر HMAC ويُعرض مرة واحدة عند الإنشاء.

المعامل / المدخل

invalid_image_url

خاصية تحمل URL (image، brand_logo، logo، avatar، background_image، ...) ليست URL عامًا من نوع http(s).

الإصلاح: مرّر URL عامًا قابلًا للجلب عبر https://.... تُرفض عناوين localhost وعناوين IP الخاصة والمسارات المجردة لمنع تزوير الطلبات من جانب الخادم.

الاشتراك

subscription_required (402)

وصل الطلب إلى Dynamic API لكن لا توجد خطة نشطة على حسابك. الوصول إلى API مخصص للاشتراك فقط: الخطة هي البوابة، وهي تحمل نفس تغطية وسلّم الإمكانات التي تبيعها تطبيقات FastOG. عمليات العرض نفسها غير محاسبة — لا توجد حصة عرض شهرية ولا فوترة تجاوز.

الإصلاح: اختر خطة Dynamic API في لوحة التحكم وأنشئ مفتاح API. تتضمن الاستجابة top_up_url يشير إلى صفحة الخطط.

خدمة العرض

store_blocked (403)

أوقفت FastOG عرض المتجر المرتبط بهذا المفتاح (على سبيل المثال بسبب إساءة الاستخدام أو الاستهلاك المفرط). قد تستمر الأغلفة المخزّنة مؤقتًا على الحافة في الخدمة حتى انتهاء صلاحيتها. تواصل مع الدعم لحل المشكلة؛ لا يوجد أي تغيير يمكنك إجراؤه في الطلب من شأنه إصلاح ذلك.

render_unreachable

تعذّر الوصول إلى خدمة العرض (نافذة إعادة تشغيل قصيرة).

الحل: أعد المحاولة بعد بضع ثوانٍ. لم يُحتسب العرض لهذه المحاولة.

render_failed

أعادت خدمة العرض خطأً لطلبك.

الحل: تحقّق من خصائص القالب (template props) — قيم طويلة أو مشوّهة، أو حقول غير مدعومة، أو صورة مصدرية (upstream) يتعذّر الوصول إليها. يتضمّن الرد تفاصيل status الأساسية. لم يُحتسب العرض.

واجهات إدارة المتجر

تُرجع هذه الرموز استجاباتها من لوحة إدارة Shopify ومن WooCommerce Studio — المحرّرات المضمّنة التي يعمل فيها التاجر بدلًا من الـ API الموقّع. تشترك عدة رموز مع الـ API العام (invalid_image_url، render_failed، invalid_signature)؛ ويحتفظ كل منها بالمدخل الموثّق أعلاه.

جسر Wix

يُوقَّع جسر Wix بواسطة تطبيق Wix، وليس بجلسة تاجر، لذا تُوجَّه إخفاقاته إلى مطوّر التطبيق. ما زال كل ردّ يحمل code وrequest_id؛ ومعرّف طلب الجسر هو المعرّف الوارد في المغلّف الموقَّع.

واجهة العرض التجريبي

العرض التجريبي هو وحدة تحكم المبيعات المخصّصة للمالك فقط، وليس نقطة نهاية للتاجر.

رموز محررات القواعد النطاقية

تُترجم محررات القواعد النطاقية (لوحة إدارة Shopify وWooCommerce Studio) هذه الرموز بنفسها إلى لغة التاجر نفسها، لذا تحمل استجاباتها error وcode دون hint — إذ لن يؤدي وصف إنجليزي ثانٍ إلا إلى الانحراف عن الوصف المترجم الذي يراه التاجر فعليًا:

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.

ما زلت عالقًا؟

• افتح صفحة Render Logs في لوحة التحكم — تُدرج كل نتيجة (نجاح + رفض) مع error_code وحالة HTTP والمعاملات المطلوبة.
• نفّذ php artisan og:diagnose على URL موقّع لتتبّع المسار كاملًا ومعرفة المرحلة التي تفشل.
• راجع الوثائق في الشريط الجانبي الخاصة بالإطار الذي تستخدمه (Next.js، Express، SvelteKit، ...).