حلّ مشكلات الحزمة
الأخطاء التي تطلقها الحزمة ووحدة Nuxt والأداة، ومعنى كل واحد منها، والحل.
هذه الصفحة لمن يحدّق في خطأ من @dukkan.one/app-sdk أو @dukkan.one/nuxt أو dukkan app. يسمّي كل بند السبب والحل؛ وحيث تملك صفحة في البوابة الحل، تجد رابطها.
الأخطاء التي تطلقها الحزمة#
يرث كل خطأ من DukkanError ويحمل code ثابتاً؛ وتضيف أخطاء الواجهة status وrequestId وdetails من غلاف الأخطاء في المنصّة.
| الخطأ | المعنى | الحل |
|---|---|---|
DukkanAuthError مع reason: "invalid_token" |
رُفض رمز الوصول. جدّدت الحزمة مرة وأعادت المحاولة أصلاً؛ فهذا يعني أن التجديد فشل أيضاً. | راجع DukkanReconnectRequiredError أدناه؛ وإلا فساعة خادمك منحرفة أكثر مما يسمح به عمر الرمز. |
DukkanAuthError مع reason: "access_removed" |
فقد العضو المانح وصوله إلى المتجر. | أرسل التاجر إلى شاشة الموافقة من جديد (الإيقاف). |
DukkanAuthError مع reason: "no_permissions" |
لم يعد التثبيت يحمل أي نطاقات فعلية. | الحل نفسه: إعادة الموافقة. |
DukkanReconnectRequiredError |
لا رموز للتثبيت في المخزن، أو أجاب التجديد بـ invalid_grant وعُلّم الصف. |
اعرض شاشة «إعادة الاتصال» لديك؛ يثبّت التاجر من جديد. لا تعِد محاولة التجديد في حلقة أبداً. |
ScopeLostError |
403: يحتاج الاستدعاء أو الموضوع نطاقاً لا يحمله التثبيت. يسمّي topics المواضيع المرفوضة. |
اطلب النطاق في dukkan.app.toml وأعد الموافقة، أو أسقط الاستدعاء. |
DukkanRateLimitError |
429 بعد رصيد إعادة المحاولة في الحزمة. retryAfterSeconds هو رقم الخادم. |
خفّف السرعة؛ الحدود في مرجع الواجهة. |
IdempotencyConflictError |
أُرسل Idempotency-Key نفسه بحمولة مختلفة، أو ما زال قيد المعالجة (inProgress). |
اشتقّ المفتاح من هوية الكتابة (idempotency: { ref })، لا من المحاولة أبداً. |
InvalidTransitionError |
لا يستطيع الطلب الانتقال من حالته الحالية إلى المطلوبة. يقول details.current_status أين هو. |
اقرأ مصفوفة الحالات؛ اجلب الطلب وقرّر من جديد. |
DukkanWebhookError (في constructEvent فقط) |
رُفض التسليم: bad_signature أو stale_timestamp أو missing_headers أو malformed_envelope أو store_mismatch أو body_too_large. |
راجع قسم المستقبِل أدناه. |
DukkanConfigError |
فشل dukkan.app.toml في التحقق؛ تسرد الرسالة كل مشكلة. |
ملف dukkan.app.toml. |
DukkanNetworkError |
تعذّر الوصول إلى المنصّة أو انتهت المهلة (15 ثانية). | أعد المحاولة لاحقاً؛ أعادت الحزمة أصلاً محاولة الاستدعاءات الآمنة للتكرار. |
يجيب مستقبِل Webhooks برفض#
| الجسم | الحالة | السبب | الحل |
|---|---|---|---|
bad_signature |
401 |
السر خاطئ، أو أُعيد تسلسل الجسم قبل التحقق. | حمّل السر الذي صكّته المنصّة لـ هذا التثبيت؛ مرّر بايتات الطلب الخام. |
stale_timestamp |
400 |
التسليم أقدم من 5 دقائق، أو ساعتك منحرفة. | زامن ساعة الخادم؛ التسليم المتأخر فعلاً تعيده المنصّة بتوقيع جديد. |
missing_headers |
400 |
لا X-Dukkan-Timestamp أو X-Dukkan-Hmac-Sha256. |
وكيل يزيل الترويسات المخصصة؛ مرّرها. |
unknown_install |
404 |
أعادت secretsFor قيمة null، أو يختلف install_id الموقّع عن تلميح الترويسة. |
خزّن السر وقت التثبيت (webhookSecrets.save)؛ تعيد المنصّة المحاولة حتى تفعل. |
store_mismatch |
403 |
store_id في الغلاف ليس المتجر الذي ربطت التثبيت به. |
لا يحدث لتثبيت مخزّن بشكل صحيح؛ افحص الربط لديك. |
body_too_large |
413 |
أكبر من 256 KB. | لا ترسل المنصّة ذلك أبداً؛ ابحث عن وكيل يغلّف الأجسام. |
malformed_envelope |
400 |
بايتات موثّقة ليست غلاف v1. | أبلغ عنه مع X-Request-Id؛ هذا خلل في المنصّة. |
تعني الإجابة { "ok": true, "duplicate": true } أن الصندوق الوارد يحمل معرّف الحدث أصلاً: أعادت المنصّة تسليماً كنت أقررت به. لا شيء يُصلح.
وحدة Nuxt#
| الرسالة | الحل |
|---|---|
Dukkan app is not configured: NUXT_DUKKAN_CLIENT_SECRET is not set (503، أو رفض الإقلاع في الإنتاج) |
اضبط المتغير؛ القائمة الكاملة في البيئة. |
sessionSecret must be at least 32 characters |
ولّد واحداً: openssl rand -base64 48. |
dukkan.app.toml not found عند البناء |
شغّل dukkan app init، أو وجّه خيار configFile في الوحدة إلى الملف. |
server/dukkan.ts not found |
أنشئه بـ defineDukkanApp؛ راجع جانبك من العقد. |
oauth_state_mismatch عند إعادة التوجيه |
انتهت Cookie الحالة (10 دقائق)، أو وصلت إعادة التوجيه على مضيف غير مضيف طلب التثبيت، أو Cookies محظورة. تأكد أن NUXT_DUKKAN_APP_BASE_URL يطابق المضيف الذي يستخدمه التجار. |
store_not_allowed عند إعادة التوجيه |
نفق عام مفتوح وNUXT_DUKKAN_ALLOWED_STORE_IDS يحصر التثبيتات في متجرك التجريبي. متوقّع أثناء التطوير. |
token_exchange_failed:invalid_grant |
استُخدم الكود مرتين أو يختلف رابط إعادة التوجيه عن المسجّل بايتاً ببايت. |
الأداة#
| الرسالة | الحل |
|---|---|
✗ Not signed in. Run: dukkan login |
سجّل الدخول؛ الاعتمادات مربوطة بمتجر تجريبي واحد. |
✗ The app is not running on port 3000 with dev routes |
شغّله بـ dukkan app dev؛ تحتاج التجارب إلى مسارات التطوير الموجودة في nuxt dev فقط. |
✗ The portal draft changed since your last pull |
اسحب، أو ادفع بـ --force؛ راجع الاختلاف. |
✗ This draft is under marketplace review and frozen |
اسحب الإرسال في البوابة أولاً. |
✗ clients:read needs the accepted data processing agreement |
اقبلها في صفحة الحساب في البوابة (النطاقات). |
✗ The platform refused the rehearsal |
المتاجر التجريبية فقط؛ يجب أن يتضمن الاشتراك الموضوع؛ ويحتاج المتجر التجريبي إلى بيانات مزروعة (المتاجر التجريبية). |
cloudflared غير موجود |
ثبّته، أو مرّر --tunnel-url مع أي نفق HTTPS، أو شغّل --no-tunnel واستخدم webhook trigger --local. |
يقبل كل أمر في الأداة --json لكائن JSON واحد في كل سطر عندما تحتاج إلى أتمتته. قائمة الأوامر الكاملة في مرجع الأداة.