مرجع الأخطاء
كل رد غير 2xx له الجسم نفسه الموصوف في الاصطلاحات: code وmessage وstatus وdetails وtraceId. ابنِ برامجك على code لأنه ثابت. أما message فعربية افتراضياً وإنجليزية حين تفضّلها Accept-Language، وقد تتحسن صياغتها مع الوقت.
- الرموز العامة مثل
unauthorizedوforbiddenوvalidation_failedتصف نوع الفشل. - رموز الأعمال بالشكل
area.reason، مثلshipment.not_foundأوmerchant.possible_duplicate. وحالة HTTP تتبع السبب:404لعدم الوجود، و409للتعارض والتكرار، و403لغير المسموح، و422لمخالفة القواعد. - رموز الأماكن (
geo_country_not_foundوgeo_city_not_foundوgeo_district_not_foundوgeo_city_ambiguousوgeo_district_ambiguous) ترد دائماً422وتحملlevelوinputوfieldوcandidatesفيdetails. راجع الأماكن بالاسم. - الطلب الذي يخالف قاعدة عمل بلا رمز مستقل يرد
422 business_rule_violationوالشرح فيmessage.
هذا الفهرس مكتوب يدوياً من تعريفات أخطاء الواجهة العامة. يبني الخادم قائمته الكاملة تلقائياً من نصوص أخطائه الداخلية، ولذلك لا يمكن استخراجها عند بناء هذا الموقع؛ ويسرد الجدول الرموز التي توثقها النقاط العامة والتي يصادفها المطورون عملياً. والحالة المذكورة هي المعتادة للرمز. وبعض الحالات قد تُبلَّغ أيضاً بالرمز validation_failed مع مسار الحقل في details.errors: غياب العنوان الوطني المختصر في شحنة مثال على ذلك. تعامل دائماً مع الحالات العامة (400 و401 و403 و404 و409 و422 و429 و500) كاحتياط لرمز لا تعرفه.
رموز عامة
| الرمز | HTTP | ما يسمح به | ما يجب فعله |
|---|---|---|---|
unauthorized | 401 | المصادقة مفقودة أو الاعتماد خاطئ. تحدد الرسالة السبب: ترويسة السر مفقودة، أو المفتاح/السر غير صحيح، أو المفتاح ملغى أو منتهي. | أرسل X-API-Key و X-API-Secret معاً أو رمز Bearer صالحاً. أنشئ مفتاحاً جديداً إن كان القديم ملغى أو منتهياً. جدّد رمز الوصول المنتهي عبر /auth/refresh. |
ambiguous_credentials | 400 | يحمل الطلب رمز Authorization: Bearer وترويسة X-API-Key معاً. | أرسل نوعاً واحداً فقط من الاعتماد. افحص وجود وسيط أو عميل يضيف ترويسة زائدة. |
forbidden | 403 | الاعتماد صالح لكنه لا يملك الصلاحية. يحدد details.requiredScope النطاق الذي تحتاجه العملية. وتسجيل الدخول بكلمة المرور يحتاج أيضاً صلاحية لوحة التحكم بالضبط (orders:create و orders:update و orders:cancel لكتابة الشحنات). | أضف النطاق إلى المفتاح من لوحة التحكم (الإعدادات ثم الربط البرمجي) أو استخدم مستخدماً يملك الصلاحية المقابلة. وحساب التاجر يحصل عليه أيضاً عند طلب بيانات تاجر آخر. |
channel_disabled | 403 | واجهة الـ API العامة غير مفعّلة لهذه الشركة: لم تمنح المنصة القناة، أو لم يشغّلها مدير الشركة. | اطلب من المنصة منح قناة الربط البرمجي ثم شغّلها من الإعدادات ثم الشركة. لا يوجد ما يُصلح في شيفرتك. |
company_required | 403 | الاعتماد لا يتبع شركة (مثل مستخدم المنصة). | استخدم مفتاح API أو مستخدماً تابعاً لشركة الشحن. |
tenant_blocked | 403 | حساب الشركة موقوف أو انتهى عقده. يُفحص مع كل طلب، فتتوقف المفاتيح والرموز القائمة فوراً. | تواصل مع المنصة. تنجح الطلبات من جديد عند إعادة تفعيل الشركة. |
validation_failed | 400 | حقل أو أكثر غير صالح، ومنها الأرقام التي تتجاوز حدها الأعلى (مثل Weight is too large). يربط details.errors كل مسار حقل (مثل recipient.phone) برسائله. | صحّح كل حقل مذكور وأعد الإرسال. اعرض الرسائل بجانب حقول النموذج. |
not_found | 404 | المسار أو المورد غير موجود. | تحقق من المسار والمعرّف. |
idempotency_key_reused | 409 | استُخدم مفتاح منع التكرار نفسه مع جسم طلب مختلف. | استخدم مفتاحاً جديداً لطلب جديد. أعد استخدام المفتاح فقط لإعادة محاولة الجسم نفسه. |
rate_limited | 429 | طلبات كثيرة جداً من عنوان IP هذا (قبل المصادقة) أو من هذا المفتاح أو المستخدم (بعدها). تعطي ترويسة Retry-After عدد الثواني للانتظار. | انتظر مدة Retry-After ثم أعد المحاولة. وزّع العمل الكبير على الزمن وخزّن نتائج القوائم (الجغرافيا والحالات). |
business_rule_violation | 422 | الطلب سليم الصياغة لكنه يخالف قاعدة عمل لا يخصها رمز مستقل. تشرح الرسالة السبب. | اقرأ الرسالة وعدّل البيانات. لا تعد المحاولة بلا تعديل. |
internal_error | 500 | خطأ غير متوقع في الخادم. اذكر traceId عند التواصل مع الدعم. | أعد المحاولة لاحقاً بمفتاح Idempotency-Key نفسه. إن استمر الخطأ فتواصل مع الدعم مع traceId. |
رموز تسجيل الدخول
| الرمز | HTTP | ما يسمح به | ما يجب فعله |
|---|---|---|---|
auth.invalid_credentials | 401 | اسم المستخدم أو كلمة المرور غير صحيحة. | اطلب من المستخدم مراجعة بياناته. تكرار الفشل يقفل الحساب. |
auth.login_temporarily_blocked | 429 | تسجيل الدخول محظور مؤقتاً من هذا الجهاز أو الشبكة بعد محاولات فاشلة متكررة. | انتظر وأعد المحاولة لاحقاً. التزم بـ Retry-After. |
auth.account_locked | 403 | الحساب مقفل مؤقتاً بعد محاولات دخول فاشلة متكررة. | انتظر انتهاء القفل أو اطلب من مدير الشركة. |
auth.account_inactive | 403 | هذا الحساب غير مفعّل. | اطلب من مدير الشركة تفعيل المستخدم. |
auth.invalid_refresh_token | 401 | رمز التجديد غير صالح أو منتهٍ. رموز التجديد تُستخدم مرة واحدة. | سجّل الدخول من جديد باسم المستخدم وكلمة المرور. احفظ دائماً رمز التجديد الجديد العائد من /auth/refresh. |
auth.company_suspended | 403 | شركة الشحن المرتبطة بهذا الحساب موقوفة. | تواصل مع المنصة. |
auth.company_expired | 403 | انتهى عقد شركة الشحن المرتبطة بهذا الحساب. | تواصل مع المنصة. |
auth.company_access_denied | 403 | لا يمكن الوصول إلى الشركة في حالتها الحالية. | تواصل مع المنصة. |
الأماكن
| الرمز | HTTP | ما يسمح به | ما يجب فعله |
|---|---|---|---|
geo_country_not_found | 422 | الدولة غير موجودة أو غير مفعّلة. يحتوي details على level و input و field و candidates. | استخدم رمز ISO (SA) أو معرّفاً أو اسماً موجوداً. اعرض candidates على المستخدم. |
geo_city_not_found | 422 | لم يتم العثور على المدينة في الدولة المحددة. | دع المستخدم يختار من candidates أو من GET /geography/cities. لا يُنشأ شيء من طلب API. |
geo_district_not_found | 422 | لم يتم العثور على الحي في المدينة المحددة. | دع المستخدم يختار من candidates أو من GET /geography/districts. |
geo_city_ambiguous | 422 | اسم المدينة يطابق أكثر من مدينة (مثلاً في دولتين). | أرسل country أيضاً أو استخدم معرّف المدينة من candidates. |
geo_district_ambiguous | 422 | اسم الحي يطابق أكثر من حي في المدينة. | استخدم معرّف الحي من candidates. |
الشحنات والتسعير والتغطية
| الرمز | HTTP | ما يسمح به | ما يجب فعله |
|---|---|---|---|
shipment.not_found | 404 | الشحنة غير موجودة. يعاد الرمز نفسه لشحنة تخص جهة أخرى. | تحقق من رقم التتبع. |
shipment.cannot_cancel | 422 | لا يمكن إلغاء الشحنة في حالتها الحالية. الإلغاء ممكن وهي مسودة أو منشأة أو مجدولة للاستلام. | اقرأ الحالة الحالية أولاً (canCancel في الشحنة). المراحل المتأخرة تمر عبر مسار الإرجاع. |
shipment.not_editable | 422 | لا يمكن تعديل شحنة في حالة نهائية (مسلّمة أو مرتجعة أو ملغاة…). | تحقق من isEditable قبل إتاحة التعديل. |
shipment.no_changes | 422 | لم يتغير أي حقل. | أرسل حقلاً واحداً على الأقل بقيمة جديدة. |
shipment.field_locked_out_for_delivery | 422 | الشحنة خرجت للتوصيل: يمكن تعديل بيانات التواصل والعنوان ومبلغ التحصيل فقط. | عدّل هذه الحقول فقط الآن. |
shipment.invalid_status_transition | 422 | لا يمكن نقل الشحنة إلى تلك الحالة من حالتها الحالية. | أعد قراءة الشحنة وتصرّف وفق حالتها الحالية. |
shipment.reverse_cod_not_allowed | 422 | لا يمكن أن تحمل شحنات الإرجاع مبلغ تحصيل عند الاستلام. | أرسل codAmount بقيمة 0 (أو احذف payment) عند serviceType = return. |
shipment.service_type_locked | 422 | لا يمكن تغيير نوع الخدمة بعد إنشاء شحنة الإرجاع المرتبطة. | ألغِ وأنشئ شحنة جديدة بدلاً من ذلك. |
shipment.multi_package_metrics | 422 | لهذه الشحنة عدة طرود؛ لا يمكن تعديل الأوزان والأبعاد هنا. | ألغِ وأعد الإنشاء إن كانت بيانات الطرد خاطئة. |
shipment.access_denied | 403 | غير مسموح لك بالوصول إلى هذه الشحنة. | استخدم اعتماداً يملك الشحنة. |
shipment.concurrency_conflict | 409 | تغيّرت الشحنة بواسطة جهة أخرى في اللحظة نفسها. | اقرأها من جديد وأعد التعديل. |
shipment.client_account_not_found | 404 | حساب التاجر مفقود أو غير صالح. | تحقق من sender.merchant. |
shipment.client_account_inactive | 422 | حساب التاجر غير مفعّل. | فعّل التاجر من لوحة التحكم. |
shipment.branch_not_found | 404 | الفرع غير موجود. | تحقق من pickup.branch مقابل GET /branches. |
branch.not_found | 404 | الفرع غير موجود أو غير مفعّل. | استخدم معرّف أو رمز أو اسم فرع مفعّل من GET /branches. |
branch.ambiguous | 422 | أكثر من فرع يحمل هذا الاسم. | استخدم رمز الفرع أو معرّفه. |
branch_coverage.no_coverage_for_city | 422 | لا يوجد فرع يغطي مدينة الاستلام. | حدّد الفرع صراحة عبر pickup.branch. |
branch_coverage.ambiguous_coverage | 422 | أكثر من فرع يغطي مدينة الاستلام. | حدّد الفرع صراحة عبر pickup.branch. |
coverage.destination_not_covered | 422 | مدينة المستلم خارج تغطية الشركة. | تحقق من GET /geography/coverage قبل الطلب. عرض السعر يبلغ عنها بـ deliverable: false بدل خطأ. |
coverage.pickup_not_covered | 422 | مدينة الاستلام خارج تغطية الشركة. | اختر مدينة استلام تخدمها الشركة. |
short_address.invalid | 422 | العنوان المختصر يجب أن يكون 4 أحرف تتبعها 4 أرقام، مثل RNBA6769. | تحقق من الصيغة في نموذجك. |
short_address.required_for_saudi_pickup | 422 | العنوان المختصر للمرسل مطلوب للاستلام داخل السعودية. | أرسل pickup.shortAddress. ملاحظة: القاعدة نفسها تُعاد عادة بالرمز validation_failed مع مسار الحقل. |
short_address.required_for_saudi_destination | 422 | العنوان المختصر للمستلم مطلوب للتوصيل داخل السعودية. | أرسل recipient.shortAddress. |
district.required_for_destination | 422 | حي المستلم مطلوب. | أرسل recipient.district. |
district.required_for_pickup | 422 | حي الاستلام مطلوب. | أرسل pickup.district. |
district.required_for_address | 422 | الحي مطلوب في العنوان. | أرسل الحي. |
district.merchant_address_without_district | 422 | عنوان التاجر المحفوظ بلا حي. | حدّث عنوان التاجر أولاً أو أرسل pickup صراحة. |
quota.monthly_shipments_limit_reached | 403 | بلغت الشركة حدها الشهري من الشحنات. | تواصل مع المنصة لرفع الحد. |
pricing.default_rate_card_not_found | 404 | ليس لدى الشركة بطاقة أسعار بعد. | أنشئ بطاقة أسعار من لوحة التحكم. |
pricing.city_not_found | 404 | المدينة غير موجودة. | تحقق من المدينة. |
pricing.merchant_not_found | 404 | حساب التاجر غير موجود. | تحقق من التاجر. |
التجار
| الرمز | HTTP | ما يسمح به | ما يجب فعله |
|---|---|---|---|
merchant.not_found | 404 | التاجر غير موجود. | تحقق من معرّف التاجر أو اسمه. |
merchant.ambiguous | 422 | أكثر من تاجر يحمل هذا الاسم. يسردهم details.candidates. | استخدم معرّف التاجر. |
merchant.address_not_found | 404 | العنوان غير موجود لهذا التاجر. | اعرض عناوين التاجر واستخدم أحد معرّفاتها. |
merchant.possible_duplicate | 409 | وُجدت بيانات تطابق تاجراً آخر على المنصة. | إن كان متجراً مختلفاً فعلاً فأرسل confirmPossibleDuplicate: true. |
merchant.email_taken_format | 409 | البريد الإلكتروني يخص تاجراً قائماً على المنصة. | استخدم بريد تواصل آخر. |
merchant.same_merchant_format | 409 | يوجد تاجر بالاسم والسجل التجاري نفسيهما على المنصة. | استخدم التاجر القائم بدل إنشاء آخر. |
الـ Webhooks
| الرمز | HTTP | ما يسمح به | ما يجب فعله |
|---|---|---|---|
webhook.not_found | 404 | اشتراك الـ Webhook غير موجود. | اعرض اشتراكات التاجر واستخدم أحد معرّفاتها. |
integrations.invalid_target_url | 422 | عنوان الـ Webhook يجب أن يكون https عاماً. | استخدم عنوان https يمكن الوصول إليه من الإنترنت. |
security.unsafe_webhook_target_url | 422 | عنوان الـ Webhook يشير إلى عنوان محلي أو خاص. | استخدم عنواناً عاماً. |
integrations.empty_events_list | 422 | اختر حدثاً واحداً على الأقل. | أرسل events، مثل ["shipment.*"]. |