انتقل إلى المحتوى
ShopentlyLearn

رموز الأخطاء

إذا فشل الطلب، فتحقق من رمز الخطأ في الاستجابة. افتحه في القائمة أدناه لمعرفة ما حدث وما يمكنك فعله. يتضمن كل خطأ مثالًا للاستجابة وإرشادات حول إعادة المحاولة.

400request.malformedتعذر تحليل الطلب.
الإجراء المطلوب
راجع بنية JSON وترميز URL وهيكل الطلب.
سياسة إعادة المحاولة
أعد المحاولة بعد تصحيح الطلب.
الاستجابة
{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsمفتاح API أو رمز الوصول غير صالح، أو انتهت صلاحيته، أو تم إلغاؤه.
الإجراء المطلوب
تحقق من عنوان المتجر وبيانات الاعتماد. احصل على رمز جديد باستخدام مفتاح API نشط.
سياسة إعادة المحاولة
أعد المحاولة بعد تصحيح المصادقة؛ وتجنب تكرار طلبات الرموز غير الصالحة.
الاستجابة
{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredترويسة Authorization المطلوبة مفقودة أو نظامها غير صحيح.
الإجراء المطلوب
لإصدار رمز أو إلغائه، استخدم مفتاح API مع ApiKey في ترويسة Authorization. للطلبات الأخرى، استخدم رمز الوصول مع Bearer.
سياسة إعادة المحاولة
أعد المحاولة بعد إرسال الترويسة الصحيحة.
الاستجابة
{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedتعذر على الخدمة تحديد عنوان IP موثوق للعميل.
الإجراء المطلوب
تحقق من عنوان IP الذي يتصل منه التكامل بواجهة API. إذا استمر الخطأ، فتواصل مع الدعم الفني لدى Shopently.
سياسة إعادة المحاولة
أعد المحاولة بعد حل مشكلة تحديد عنوان IP.
الاستجابة
{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedعنوان IP المصدر غير موجود في قائمة العناوين المسموحة للمفتاح.
الإجراء المطلوب
استخدم عنوان مصدر معتمدًا، أو اطلب من مسؤول مخوّل تعديل قائمة IP للمفتاح.
سياسة إعادة المحاولة
أعد المحاولة فقط بعد السماح بالعنوان.
الاستجابة
{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedلا يملك المفتاح صلاحية فعالة مطلوبة لهذه العملية.
الإجراء المطلوب
تحقق من الصلاحيات المطلوبة والشرطية للعملية، ومن الصلاحيات الممنوحة للمفتاح ووصول من أصدره.
سياسة إعادة المحاولة
أعد المحاولة بعد أن يمنح مسؤول مخوّل الوصول المطلوب.
الاستجابة
{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledالوصول إلى API معطل لهذا المتجر.
الإجراء المطلوب
اطلب من مالك المتجر مراجعة الخطة النشطة وتوفر API.
سياسة إعادة المحاولة
لا تعد المحاولة حتى يُفعّل الوصول إلى API.
الاستجابة
{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededسيؤدي التغيير إلى تجاوز حد في الخطة الحالية.
الإجراء المطلوب
راجع الحد المطبق على المورد، وعدّل التغيير المقصود أو الخطة.
سياسة إعادة المحاولة
أعد المحاولة بعد معالجة الحد؛ واستخدم مفتاح عدم تكرار جديدًا إذا تغير الطلب.
الاستجابة
{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledالخطة الحالية لا تشمل هذه العملية.
الإجراء المطلوب
راجع الحد الأدنى للخطة الموضح لهذه العملية.
سياسة إعادة المحاولة
أعد المحاولة عندما تسمح الخطة بالعملية ويملك المفتاح الصلاحيات المطلوبة.
الاستجابة
{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedيمنع حد في الخطة الوصول إلى هذا المورد تحديدًا.
الإجراء المطلوب
اطلب من المالك معالجة قيد الخطة المفروض على المورد.
سياسة إعادة المحاولة
لا تكرر الطلب نفسه ما دام المورد محظورًا.
الاستجابة
{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundالمورد غير موجود أو محذوف أو غير متاح بالمعرّف المرسل.
الإجراء المطلوب
تحقق من المتجر ومسار المورد ومعرّفه. استخدم المعرّفات التي يعيدها هذا المتجر.
سياسة إعادة المحاولة
أعد المحاولة فقط بعد تصحيح الهدف أو التأكد من وجوده.
الاستجابة
{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedلا تدعم نقطة النهاية طريقة HTTP هذه.
الإجراء المطلوب
استخدم الطريقة الموثقة؛ وتحدد ترويسة Allow الطرق المدعومة.
سياسة إعادة المحاولة
لا تعد المحاولة باستخدام الطريقة غير المدعومة.
الاستجابة
{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedينتمي مفتاح عدم التكرار هذا إلى طلب مختلف.
الإجراء المطلوب
ابحث عن العملية الأصلية. استخدم مفتاحًا جديدًا فقط لعملية منطقية جديدة مقصودة.
سياسة إعادة المحاولة
لا تعاود إرسال محتوى مختلف بالمفتاح المتعارض.
الاستجابة
{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsتتعارض قيمة فريدة مع مورد موجود.
الإجراء المطلوب
اقرأ المورد الموجود وحدد ما إذا كنت ستستخدمه أو ستختار قيمة فريدة أخرى.
سياسة إعادة المحاولة
لا تكرر عملية الإنشاء المتعارضة نفسها.
الاستجابة
{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useلا تزال موارد أخرى تعتمد على هذا المورد.
الإجراء المطلوب
راجع التبعيات وأزلها أو غيّرها عبر العمليات المدعومة قبل الحذف.
سياسة إعادة المحاولة
أعد المحاولة بعد معالجة التبعيات.
الاستجابة
{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictتمنع حالة العمل الحالية هذا التغيير.
الإجراء المطلوب
اقرأ الحالة الحالية واختر انتقالًا صالحًا وفق قواعد العمل.
سياسة إعادة المحاولة
لا تفرض التغيير تلقائيًا ولا تكرر إرساله أثناء التعارض.
الاستجابة
{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictعدلت عملية كتابة أخرى المورد بعد الإصدار الذي قرأته.
الإجراء المطلوب
اقرأ أحدث حالة، ووفّق تغييرك معها، ثم أرسل expected_version الجديد.
سياسة إعادة المحاولة
استخدم مفتاح عدم تكرار جديدًا للعملية المعدلة؛ ولا تستبدل البيانات دون تحقق.
الاستجابة
{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409storage.limit_reachedبلغ المتجر حد تخزين الصور والملفات المرفوعة. حرر مساحة أو ارفع الحد.
الإجراء المطلوب
بلغ المتجر حد تخزين الصور والملفات المرفوعة. حرر مساحة أو ارفع الحد.
سياسة إعادة المحاولة
أعد المحاولة بعمليات أصغر صالحة، ولكل منها مفتاح عدم تكرار خاص.
الاستجابة
{
  "error": {
    "code": "storage.limit_reached",
    "fields": null,
    "message": "The upload storage limit is reached."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeيتجاوز الطلب حد الحجم.
الإجراء المطلوب
قلل حجم المحتوى أو قسم العمل إلى عمليات منفردة مدعومة.
سياسة إعادة المحاولة
أعد المحاولة بعمليات أصغر صالحة، ولكل منها مفتاح عدم تكرار خاص.
الاستجابة
{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeنوع المحتوى أو ترميزه غير مدعوم.
الإجراء المطلوب
استخدم Content-Type: application/json ومحتوى غير مضغوط مدعومًا لعمليات كتابة JSON.
سياسة إعادة المحاولة
أعد المحاولة بعد تصحيح نوع المحتوى أو ترميزه.
الاستجابة
{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

416request.range_not_satisfiableالقيود: Range
الإجراء المطلوب
Range: bytes=0-(size_bytes-1)
سياسة إعادة المحاولة
أعد المحاولة بعد تصحيح الطلب.
الاستجابة
{
  "error": {
    "code": "request.range_not_satisfiable",
    "fields": null,
    "message": "The requested byte range is unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedفشل التحقق من حقل أو معامل واحد أو أكثر.
الإجراء المطلوب
راجع error.fields، ثم تحقق من الحقول المطلوبة وإمكانية استخدام null والمعرّفات والقيم المسموحة.
سياسة إعادة المحاولة
أعد المحاولة بطلب مصحح؛ وعملية الكتابة المعدلة عملية منطقية جديدة.
الاستجابة
{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullقائمة الانتظار القصيرة لواجهة API ممتلئة؛ لم يبدأ تنفيذ الطلب.
الإجراء المطلوب
ضع الطلبات في قائمة انتظار، والتزم بترويسة الاستجابة Retry-After.
سياسة إعادة المحاولة
انتظر على الأقل عدد الثواني المحدد في Retry-After. إذا كررت عملية كتابة، فاحتفظ بمحتوى الطلب نفسه وقيمة Idempotency-Key نفسها.
الاستجابة
{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutانتهت مهلة الانتظار في قائمة واجهة API؛ لم يبدأ تنفيذ الطلب.
الإجراء المطلوب
ضع الطلبات في قائمة انتظار، والتزم بترويسة الاستجابة Retry-After.
سياسة إعادة المحاولة
انتظر على الأقل عدد الثواني المحدد في Retry-After. إذا كررت عملية كتابة، فاحتفظ بمحتوى الطلب نفسه وقيمة Idempotency-Key نفسها.
الاستجابة
{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededيتجاوز معدل الطلبات الحد المطبق.
الإجراء المطلوب
ضع الطلبات في قائمة انتظار، والتزم بترويسة الاستجابة Retry-After.
سياسة إعادة المحاولة
انتظر على الأقل عدد الثواني المحدد في Retry-After. إذا كررت عملية كتابة، فاحتفظ بمحتوى الطلب نفسه وقيمة Idempotency-Key نفسها.
الاستجابة
{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorحدث خطأ غير متوقع في الخدمة.
الإجراء المطلوب
انتظر قليلًا قبل تكرار الطلب. إذا ظهر الخطأ 500 مجددًا، فتواصل مع الدعم الفني لدى Shopently وأرفق معرّف الطلب.
سياسة إعادة المحاولة
يمكنك محاولة قراءة البيانات مجددًا بعد توقف قصير. عند تكرار عملية كتابة، استخدم قيمة Idempotency-Key نفسها ولا تغيّر محتوى الطلب.
الاستجابة
{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseلم تتلق البوابة استجابة API صالحة.
الإجراء المطلوب
احتفظ بمعرّف الطلب. لا يثبت فشل الاستجابة أن عملية الكتابة لم تُطبّق.
سياسة إعادة المحاولة
حدد عدد المحاولات وزد الانتظار؛ وكرر الكتابة المنطقية نفسها باستخدام Idempotency-Key والمحتوى الأصليين.
الاستجابة
{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableلا تستطيع API معالجة الطلب مؤقتًا.
الإجراء المطلوب
إذا تضمنت الاستجابة ترويسة Retry-After، فانتظر عدد الثواني المحدد قبل إعادة المحاولة. وإلا فانتظر قليلًا. إذا استمر الخطأ، فتواصل مع الدعم الفني لدى Shopently وأرفق معرّف الطلب.
سياسة إعادة المحاولة
أعد المحاولة بعد الانتظار كما هو موضح أعلاه. عند تكرار عملية كتابة، استخدم قيمة Idempotency-Key نفسها ولا تغيّر محتوى الطلب.
الاستجابة
{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutانتهت مهلة البوابة أثناء انتظار API.
الإجراء المطلوب
إذا كان الطلب يغيّر بيانات، فتحقق من حفظ التغييرات في المتجر. عدم وصول استجابة لا يعني فشل الحفظ. إذا استمر الخطأ، فتواصل مع الدعم الفني لدى Shopently وأرفق معرّف الطلب.
سياسة إعادة المحاولة
يمكنك محاولة قراءة البيانات مجددًا بعد توقف قصير. عند تكرار عملية كتابة، استخدم قيمة Idempotency-Key نفسها ولا تغيّر محتوى الطلب.
الاستجابة
{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}