الإجراء المطلوب
- اعتمد في المنطق على حالة HTTP وerror.code، لا على النص الموجه للمستخدم في error.message.
- تتطلب 401 مصادقة صحيحة؛ وتتطلب 403 تعديل الوصول أو الخطة؛ وتتطلب 409 التحقق من العملية المتعارضة أو إصدار المورد.
رفض الوصول وإعادة المحاولة
- 401
- لا يعني 401 دائمًا انتهاء صلاحية الرمز. إذا انتهت صلاحيته، احصل على رمز جديد وأعد طلب القراءة مرة واحدة كحد أقصى. إذا أعاد طلب الرمز 401، فتحقق من المفتاح وأوقف المحاولات التلقائية.
- 403
- عند ظهور 403، تحقق من الصلاحيات وقيود IP والخطة. الحصول على رمز جديد لا يعيد الوصول الذي تم إلغاؤه.
سياسة إعادة المحاولة
- حدد عدد محاولات إعادة الطلب عند الأعطال المؤقتة، مع زيادة فترات الانتظار وإضافة تفاوت عشوائي.
- التزم بـ Retry-After عند وجوده.
- إذا انتهت مهلة عملية كتابة، فقد تكون نتيجتها مجهولة: احتفظ بنفس Idempotency-Key وبالطلب دون تغيير عند إعادة العملية المنطقية نفسها.
- يشرح الدليل أدناه جميع رموز الأخطاء المنشورة.
422 / 409
- بالنسبة إلى الأسعار، يؤدي تنسيق العملة غير الصالح أو الدقة غير المسموح بها للمبلغ إلى 422 request.validation_failed.
- ويؤدي رمز عملة صالح لا يطابق قائمة الأسعار المحددة إلى 409 resource.version_conflict.
- تحقّق من السياق والإصدارات قبل إعادة المحاولة.
دليل الأخطاء
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 المطلوبة مفقودة أو نظامها غير صحيح.
- الإجراء المطلوب
- استخدم ApiKey عند طلب الرمز، وBearer في عمليات الموارد.
- سياسة إعادة المحاولة
- أعد المحاولة بعد إرسال الترويسة الصحيحة.
{
"error": {
"code": "authentication.required",
"fields": null,
"message": "Authentication is required."
},
"meta": {
"request_id": "example-request"
}
}
403authorization.client_ip_unverifiedتعذر على الخدمة تحديد عنوان 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"
}
}
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"
}
}
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 وأضف تفاوتًا عشوائيًا. احتفظ بالمفتاح والمحتوى الأصليين عند إعادة الكتابة.
{
"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 وأضف تفاوتًا عشوائيًا. احتفظ بالمفتاح والمحتوى الأصليين عند إعادة الكتابة.
{
"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 وأضف تفاوتًا عشوائيًا. احتفظ بالمفتاح والمحتوى الأصليين عند إعادة الكتابة.
{
"error": {
"code": "rate_limit.exceeded",
"fields": null,
"message": "The request rate limit has been exceeded."
},
"meta": {
"request_id": "example-request"
}
}
500internal.errorحدث خطأ غير متوقع في الخدمة.
- الإجراء المطلوب
- سجل معرّف الطلب واتصل بالمشغل إذا استمر الخطأ؛ واستبعد بيانات الاعتماد من السجلات.
- سياسة إعادة المحاولة
- حدد عدد المحاولات وزد الانتظار. احتفظ بمفتاح عدم التكرار الأصلي والمحتوى دون تغيير عند الكتابة.
{
"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"
}
}
504gateway.timeoutانتهت مهلة البوابة أثناء انتظار API.
- الإجراء المطلوب
- احتفظ بمعرّف الطلب وتعامل مع نتيجة الكتابة على أنها مجهولة.
- سياسة إعادة المحاولة
- حدد عدد المحاولات وزد الانتظار؛ وأعد استخدام مفتاح عدم التكرار الأصلي والمحتوى دون تغيير في الكتابة.
{
"error": {
"code": "gateway.timeout",
"fields": null,
"message": "The API gateway timed out."
},
"meta": {
"request_id": "example-request"
}
}