GROperator

جارٍ التحميل…

English

مرجع الأخطاء

كل رد غير 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ما يسمح بهما يجب فعله
unauthorized401المصادقة مفقودة أو الاعتماد خاطئ. تحدد الرسالة السبب: ترويسة السر مفقودة، أو المفتاح/السر غير صحيح، أو المفتاح ملغى أو منتهي.أرسل X-API-Key و X-API-Secret معاً أو رمز Bearer صالحاً. أنشئ مفتاحاً جديداً إن كان القديم ملغى أو منتهياً. جدّد رمز الوصول المنتهي عبر /auth/refresh.
ambiguous_credentials400يحمل الطلب رمز Authorization: Bearer وترويسة X-API-Key معاً.أرسل نوعاً واحداً فقط من الاعتماد. افحص وجود وسيط أو عميل يضيف ترويسة زائدة.
forbidden403الاعتماد صالح لكنه لا يملك الصلاحية. يحدد details.requiredScope النطاق الذي تحتاجه العملية. وتسجيل الدخول بكلمة المرور يحتاج أيضاً صلاحية لوحة التحكم بالضبط (orders:create و orders:update و orders:cancel لكتابة الشحنات).أضف النطاق إلى المفتاح من لوحة التحكم (الإعدادات ثم الربط البرمجي) أو استخدم مستخدماً يملك الصلاحية المقابلة. وحساب التاجر يحصل عليه أيضاً عند طلب بيانات تاجر آخر.
channel_disabled403واجهة الـ API العامة غير مفعّلة لهذه الشركة: لم تمنح المنصة القناة، أو لم يشغّلها مدير الشركة.اطلب من المنصة منح قناة الربط البرمجي ثم شغّلها من الإعدادات ثم الشركة. لا يوجد ما يُصلح في شيفرتك.
company_required403الاعتماد لا يتبع شركة (مثل مستخدم المنصة).استخدم مفتاح API أو مستخدماً تابعاً لشركة الشحن.
tenant_blocked403حساب الشركة موقوف أو انتهى عقده. يُفحص مع كل طلب، فتتوقف المفاتيح والرموز القائمة فوراً.تواصل مع المنصة. تنجح الطلبات من جديد عند إعادة تفعيل الشركة.
validation_failed400حقل أو أكثر غير صالح، ومنها الأرقام التي تتجاوز حدها الأعلى (مثل Weight is too large). يربط details.errors كل مسار حقل (مثل recipient.phone) برسائله.صحّح كل حقل مذكور وأعد الإرسال. اعرض الرسائل بجانب حقول النموذج.
not_found404المسار أو المورد غير موجود.تحقق من المسار والمعرّف.
idempotency_key_reused409استُخدم مفتاح منع التكرار نفسه مع جسم طلب مختلف.استخدم مفتاحاً جديداً لطلب جديد. أعد استخدام المفتاح فقط لإعادة محاولة الجسم نفسه.
rate_limited429طلبات كثيرة جداً من عنوان IP هذا (قبل المصادقة) أو من هذا المفتاح أو المستخدم (بعدها). تعطي ترويسة Retry-After عدد الثواني للانتظار.انتظر مدة Retry-After ثم أعد المحاولة. وزّع العمل الكبير على الزمن وخزّن نتائج القوائم (الجغرافيا والحالات).
business_rule_violation422الطلب سليم الصياغة لكنه يخالف قاعدة عمل لا يخصها رمز مستقل. تشرح الرسالة السبب.اقرأ الرسالة وعدّل البيانات. لا تعد المحاولة بلا تعديل.
internal_error500خطأ غير متوقع في الخادم. اذكر traceId عند التواصل مع الدعم.أعد المحاولة لاحقاً بمفتاح Idempotency-Key نفسه. إن استمر الخطأ فتواصل مع الدعم مع traceId.

رموز تسجيل الدخول

الرمزHTTPما يسمح بهما يجب فعله
auth.invalid_credentials401اسم المستخدم أو كلمة المرور غير صحيحة.اطلب من المستخدم مراجعة بياناته. تكرار الفشل يقفل الحساب.
auth.login_temporarily_blocked429تسجيل الدخول محظور مؤقتاً من هذا الجهاز أو الشبكة بعد محاولات فاشلة متكررة.انتظر وأعد المحاولة لاحقاً. التزم بـ Retry-After.
auth.account_locked403الحساب مقفل مؤقتاً بعد محاولات دخول فاشلة متكررة.انتظر انتهاء القفل أو اطلب من مدير الشركة.
auth.account_inactive403هذا الحساب غير مفعّل.اطلب من مدير الشركة تفعيل المستخدم.
auth.invalid_refresh_token401رمز التجديد غير صالح أو منتهٍ. رموز التجديد تُستخدم مرة واحدة.سجّل الدخول من جديد باسم المستخدم وكلمة المرور. احفظ دائماً رمز التجديد الجديد العائد من /auth/refresh.
auth.company_suspended403شركة الشحن المرتبطة بهذا الحساب موقوفة.تواصل مع المنصة.
auth.company_expired403انتهى عقد شركة الشحن المرتبطة بهذا الحساب.تواصل مع المنصة.
auth.company_access_denied403لا يمكن الوصول إلى الشركة في حالتها الحالية.تواصل مع المنصة.

الأماكن

الرمزHTTPما يسمح بهما يجب فعله
geo_country_not_found422الدولة غير موجودة أو غير مفعّلة. يحتوي details على level و input و field و candidates.استخدم رمز ISO (SA) أو معرّفاً أو اسماً موجوداً. اعرض candidates على المستخدم.
geo_city_not_found422لم يتم العثور على المدينة في الدولة المحددة.دع المستخدم يختار من candidates أو من GET /geography/cities. لا يُنشأ شيء من طلب API.
geo_district_not_found422لم يتم العثور على الحي في المدينة المحددة.دع المستخدم يختار من candidates أو من GET /geography/districts.
geo_city_ambiguous422اسم المدينة يطابق أكثر من مدينة (مثلاً في دولتين).أرسل country أيضاً أو استخدم معرّف المدينة من candidates.
geo_district_ambiguous422اسم الحي يطابق أكثر من حي في المدينة.استخدم معرّف الحي من candidates.

الشحنات والتسعير والتغطية

الرمزHTTPما يسمح بهما يجب فعله
shipment.not_found404الشحنة غير موجودة. يعاد الرمز نفسه لشحنة تخص جهة أخرى.تحقق من رقم التتبع.
shipment.cannot_cancel422لا يمكن إلغاء الشحنة في حالتها الحالية. الإلغاء ممكن وهي مسودة أو منشأة أو مجدولة للاستلام.اقرأ الحالة الحالية أولاً (canCancel في الشحنة). المراحل المتأخرة تمر عبر مسار الإرجاع.
shipment.not_editable422لا يمكن تعديل شحنة في حالة نهائية (مسلّمة أو مرتجعة أو ملغاة…).تحقق من isEditable قبل إتاحة التعديل.
shipment.no_changes422لم يتغير أي حقل.أرسل حقلاً واحداً على الأقل بقيمة جديدة.
shipment.field_locked_out_for_delivery422الشحنة خرجت للتوصيل: يمكن تعديل بيانات التواصل والعنوان ومبلغ التحصيل فقط.عدّل هذه الحقول فقط الآن.
shipment.invalid_status_transition422لا يمكن نقل الشحنة إلى تلك الحالة من حالتها الحالية.أعد قراءة الشحنة وتصرّف وفق حالتها الحالية.
shipment.reverse_cod_not_allowed422لا يمكن أن تحمل شحنات الإرجاع مبلغ تحصيل عند الاستلام.أرسل codAmount بقيمة 0 (أو احذف payment) عند serviceType = return.
shipment.service_type_locked422لا يمكن تغيير نوع الخدمة بعد إنشاء شحنة الإرجاع المرتبطة.ألغِ وأنشئ شحنة جديدة بدلاً من ذلك.
shipment.multi_package_metrics422لهذه الشحنة عدة طرود؛ لا يمكن تعديل الأوزان والأبعاد هنا.ألغِ وأعد الإنشاء إن كانت بيانات الطرد خاطئة.
shipment.access_denied403غير مسموح لك بالوصول إلى هذه الشحنة.استخدم اعتماداً يملك الشحنة.
shipment.concurrency_conflict409تغيّرت الشحنة بواسطة جهة أخرى في اللحظة نفسها.اقرأها من جديد وأعد التعديل.
shipment.client_account_not_found404حساب التاجر مفقود أو غير صالح.تحقق من sender.merchant.
shipment.client_account_inactive422حساب التاجر غير مفعّل.فعّل التاجر من لوحة التحكم.
shipment.branch_not_found404الفرع غير موجود.تحقق من pickup.branch مقابل GET /branches.
branch.not_found404الفرع غير موجود أو غير مفعّل.استخدم معرّف أو رمز أو اسم فرع مفعّل من GET /branches.
branch.ambiguous422أكثر من فرع يحمل هذا الاسم.استخدم رمز الفرع أو معرّفه.
branch_coverage.no_coverage_for_city422لا يوجد فرع يغطي مدينة الاستلام.حدّد الفرع صراحة عبر pickup.branch.
branch_coverage.ambiguous_coverage422أكثر من فرع يغطي مدينة الاستلام.حدّد الفرع صراحة عبر pickup.branch.
coverage.destination_not_covered422مدينة المستلم خارج تغطية الشركة.تحقق من GET /geography/coverage قبل الطلب. عرض السعر يبلغ عنها بـ deliverable: false بدل خطأ.
coverage.pickup_not_covered422مدينة الاستلام خارج تغطية الشركة.اختر مدينة استلام تخدمها الشركة.
short_address.invalid422العنوان المختصر يجب أن يكون 4 أحرف تتبعها 4 أرقام، مثل RNBA6769.تحقق من الصيغة في نموذجك.
short_address.required_for_saudi_pickup422العنوان المختصر للمرسل مطلوب للاستلام داخل السعودية.أرسل pickup.shortAddress. ملاحظة: القاعدة نفسها تُعاد عادة بالرمز validation_failed مع مسار الحقل.
short_address.required_for_saudi_destination422العنوان المختصر للمستلم مطلوب للتوصيل داخل السعودية.أرسل recipient.shortAddress.
district.required_for_destination422حي المستلم مطلوب.أرسل recipient.district.
district.required_for_pickup422حي الاستلام مطلوب.أرسل pickup.district.
district.required_for_address422الحي مطلوب في العنوان.أرسل الحي.
district.merchant_address_without_district422عنوان التاجر المحفوظ بلا حي.حدّث عنوان التاجر أولاً أو أرسل pickup صراحة.
quota.monthly_shipments_limit_reached403بلغت الشركة حدها الشهري من الشحنات.تواصل مع المنصة لرفع الحد.
pricing.default_rate_card_not_found404ليس لدى الشركة بطاقة أسعار بعد.أنشئ بطاقة أسعار من لوحة التحكم.
pricing.city_not_found404المدينة غير موجودة.تحقق من المدينة.
pricing.merchant_not_found404حساب التاجر غير موجود.تحقق من التاجر.

التجار

الرمزHTTPما يسمح بهما يجب فعله
merchant.not_found404التاجر غير موجود.تحقق من معرّف التاجر أو اسمه.
merchant.ambiguous422أكثر من تاجر يحمل هذا الاسم. يسردهم details.candidates.استخدم معرّف التاجر.
merchant.address_not_found404العنوان غير موجود لهذا التاجر.اعرض عناوين التاجر واستخدم أحد معرّفاتها.
merchant.possible_duplicate409وُجدت بيانات تطابق تاجراً آخر على المنصة.إن كان متجراً مختلفاً فعلاً فأرسل confirmPossibleDuplicate: true.
merchant.email_taken_format409البريد الإلكتروني يخص تاجراً قائماً على المنصة.استخدم بريد تواصل آخر.
merchant.same_merchant_format409يوجد تاجر بالاسم والسجل التجاري نفسيهما على المنصة.استخدم التاجر القائم بدل إنشاء آخر.

الـ Webhooks

الرمزHTTPما يسمح بهما يجب فعله
webhook.not_found404اشتراك الـ Webhook غير موجود.اعرض اشتراكات التاجر واستخدم أحد معرّفاتها.
integrations.invalid_target_url422عنوان الـ Webhook يجب أن يكون https عاماً.استخدم عنوان https يمكن الوصول إليه من الإنترنت.
security.unsafe_webhook_target_url422عنوان الـ Webhook يشير إلى عنوان محلي أو خاص.استخدم عنواناً عاماً.
integrations.empty_events_list422اختر حدثاً واحداً على الأقل.أرسل events، مثل ["shipment.*"].