Code

رموز الخطأ الأساسية لواجهات برمجة التطبيقات gRPC API

قد يتم أحيانًا تطبيق عدة رموز خطأ. يجب أن تعرض الخدمات رمز الخطأ الأكثر تحديدًا الذي ينطبق. على سبيل المثال، يمكنك تفضيل OUT_OF_RANGE على FAILED_PRECONDITION إذا تم تطبيق كلا الرمزين. وبالمثل، يتم تفضيل NOT_FOUND أو ALREADY_EXISTS على FAILED_PRECONDITION.

عمليات التعداد
OK

حدث خطأ ولم يتم عرض الخطأ.

ربط HTTP: 200 حسنًا

CANCELLED

تم إلغاء العملية عادةً بواسطة المتصل.

ربط HTTP: 499 طلب مغلق من قِبل العميل

UNKNOWN

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

تعيين HTTP: خطأ في الخادم الداخلي 500

INVALID_ARGUMENT

حدَّد العميل وسيطة غير صالحة. ملاحظة: تختلف هذه القيمة عن FAILED_PRECONDITION. تشير السمة INVALID_ARGUMENT إلى وسيطات بها مشاكل بغض النظر عن حالة النظام (مثلاً، اسم ملف غير صحيح).

تعيين HTTP: 400 طلب غير صالح

DEADLINE_EXCEEDED

انتهت صلاحية الموعد النهائي قبل اكتمال العملية. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى في حال اكتمال العملية بنجاح. على سبيل المثال، قد يتأخّر ردّ ناجح من خادم لفترة طويلة بما يكفي لكي تنتهي صلاحية الموعد النهائي.

ربط HTTP: انتهاء مهلة مدخل 504

NOT_FOUND

لم يتم العثور على كيان مطلوب (مثل ملف أو دليل).

ملاحظة لمطوّري الخوادم: إذا تم رفض طلب لفئة كاملة من المستخدمين، مثل طرح الميزة تدريجيًا أو القائمة المسموح بها غير الموثَّقة، قد يتم استخدام NOT_FOUND. إذا تم رفض طلب لبعض المستخدمين ضمن فئة من المستخدمين، مثل عنصر التحكّم في الوصول المستند إلى المستخدم، يجب استخدام PERMISSION_DENIED.

ربط HTTP: 404 لم يتم العثور على الصفحة

ALREADY_EXISTS

الكيان الذي حاول العميل إنشاءه (مثل ملف أو دليل) موجود سلفًا.

ربط HTTP: 409 تعارض

PERMISSION_DENIED

ليس لدى المتصل إذن بتنفيذ العملية المحددة. يجب عدم استخدام PERMISSION_DENIED في حالات الرفض الناتجة عن استنفاد بعض الموارد (استخدِم RESOURCE_EXHAUSTED بدلاً من هذه الأخطاء). يجب عدم استخدام الرقم PERMISSION_DENIED في حال تعذّر تحديد المتصل (يمكن استخدام UNAUTHENTICATED بدلاً من الأخطاء). لا يشير رمز الخطأ هذا إلى أن الطلب صالح أو أن الكيان المطلوب موجود أو يستوفي شروطًا مُسبَقة أخرى.

ربط HTTP: 403 محظور

UNAUTHENTICATED

لا يحتوي الطلب على بيانات اعتماد مصادقة صالحة للعملية.

ربط HTTP: 401 غير مصرّح به

RESOURCE_EXHAUSTED

تم استنفاد بعض الموارد، أو ربما تم تجاوز الحصة المخصصة لكل مستخدم، أو ربما نفدت مساحة التخزين في نظام الملفات بالكامل.

ربط HTTP: 429 عدد كبير جدًا من الطلبات

FAILED_PRECONDITION

تم رفض العملية لأن النظام ليس في الحالة المطلوبة لتنفيذ العملية. على سبيل المثال، الدليل الذي سيتم حذفه غير فارغ، يتم تطبيق عملية rmdir على دليل غير الدليل، إلخ.

يمكن لمنفذي الخدمات استخدام الإرشادات التالية لاتخاذ قرار بشأن بين FAILED_PRECONDITION وABORTED وUNAVAILABLE: (أ) استخدام UNAVAILABLE إذا كان بإمكان العميل إعادة محاولة إجراء المكالمة التي تعذّر تنفيذها فقط. (ب) استخدِم ABORTED إذا كان على العميل إعادة المحاولة على مستوى أعلى. على سبيل المثال، عند تعذّر اختبار وضبط المحتوى من تحديد العميل، يشير ذلك إلى أنّه على العميل إعادة تشغيل تسلسل Read-mod-write. (ج) استخدِم FAILED_PRECONDITION إذا لم يتمكّن العميل من إعادة المحاولة حتى يتم إصلاح حالة النظام بشكلٍ صريح. على سبيل المثال، إذا تعذّر تنفيذ "rmdir" لأن الدليل غير فارغ، يجب عرض FAILED_PRECONDITION لأنّ البرنامج يجب ألا يعيد المحاولة ما لم يتم حذف الملفات من الدليل.

تعيين HTTP: 400 طلب غير صالح

ABORTED

تم إلغاء العملية في العادة، بسبب مشكلة في التزامن مثل تعذّر التحقّق من التسلسل أو إلغاء العملية.

يُرجى الاطّلاع على الإرشادات أعلاه لتحديد ما بين FAILED_PRECONDITION وABORTED وUNAVAILABLE.

ربط HTTP: 409 تعارض

OUT_OF_RANGE

تمت محاولة العملية بعد النطاق الصحيح. على سبيل المثال، تقديم/ترجيع أو قراءة نهاية الملف

على عكس INVALID_ARGUMENT، يشير هذا الخطأ إلى مشكلة قد يتم حلّها في حال تغيّرت حالة النظام. على سبيل المثال، سيعمل نظام الملفات 32 بت على إنشاء INVALID_ARGUMENT إذا طُلِب منه الإزاحة التي لا تقع في النطاق [0,2^32-1]، ولكن سيُنشئ OUT_OF_RANGE إذا طُلِب القراءة من إزاحة تتجاوز حجم الملف الحالي.

هناك بعض التداخل بين FAILED_PRECONDITION وOUT_OF_RANGE. ننصح باستخدام OUT_OF_RANGE (الخطأ الأكثر تحديدًا) عند تطبيقه حتى يتمكّن المتصِلون الذين يكرّرون الزيارة من خلال مساحة العمل من البحث بسهولة عن خطأ OUT_OF_RANGE لرصد وقت الانتهاء.

تعيين HTTP: 400 طلب غير صالح

UNIMPLEMENTED

لم يتم تنفيذ العملية أو كانت غير متاحة أو مفعّلة في هذه الخدمة.

ربط HTTP: 501 لم يتم التنفيذ

INTERNAL

أخطاء داخلية. ويعني ذلك أنّ بعض الثوابت التي توقّعها النظام الأساسي قد تعطّلت. رمز الخطأ هذا محجوز للأخطاء الخطيرة.

تعيين HTTP: خطأ في الخادم الداخلي 500

UNAVAILABLE

هذه الخدمة غير متاحة حاليًا. هذه الحالة على الأرجح عابرة، ويمكن تصحيحها من خلال إعادة المحاولة باستخدام تراجع. يُرجى العِلم أنّه من غير الآمن دائمًا إعادة محاولة إجراء عمليات غير محتمَلة.

يُرجى الاطّلاع على الإرشادات أعلاه لتحديد ما بين FAILED_PRECONDITION وABORTED وUNAVAILABLE.

خريطة HTTP: خدمة 503 غير متوفرة

DATA_LOSS

البيانات أو التلف غير القابل للاسترداد

تعيين HTTP: خطأ في الخادم الداخلي 500