Code

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

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

عمليات التعداد
OK	ليس خطأ، بل يتم إرجاعه عند النجاح. تعيين HTTP: 200 OK
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 Too Many Requests
FAILED_PRECONDITION	تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذ العملية. على سبيل المثال، الدليل الذي سيتم حذفه غير فارغ، أو تم تطبيق عملية rmdir على عنصر غير دليل، وما إلى ذلك. يمكن لمنفّذِي الخدمة استخدام الإرشادات التالية لاختيار بين FAILED_PRECONDITION وABORTED وUNAVAILABLE: (أ) استخدِم UNAVAILABLE إذا كان بإمكان العميل إعادة محاولة طلب الاتصال الذي تعذّر إكماله فقط. (ب) استخدِم ABORTED إذا كان على العميل إعادة المحاولة على مستوى أعلى. على سبيل المثال، عندما يتعذّر إجراء عملية اختبار وضبط يحدّدها العميل، يشير ذلك إلى أنّه على العميل إعادة تشغيل تسلسل القراءة والتعديل والكتابة. (ج) استخدِم 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 Not Implemented
INTERNAL	الأخطاء الداخلية وهذا يعني أنّه تمّ انتهاك بعض الشروط الثابتة التي يتوقّعها النظام الأساسي. تم حجز رمز الخطأ هذا للأخطاء الخطيرة. تعيين HTTP: 500 خطأ في الخادم الداخلي
UNAVAILABLE	هذه الخدمة غير متاحة حاليًا. من المرجّح أنّ هذا الموقف عابر، ويمكن تصحيحه من خلال إعادة المحاولة مع الانتظار. يُرجى العِلم أنّه ليس من الآمن دائمًا إعادة محاولة العمليات غير الثابتة. اطّلِع على الإرشادات أعلاه لتحديد ما إذا كنت تريد استخدام FAILED_PRECONDITION أو ABORTED أو UNAVAILABLE. تعيين HTTP: 503 الخدمة غير متاحة
DATA_LOSS	ثمة بيانات تالفة أو مفقودة ويتعذّر استرجاعها. تعيين HTTP: 500 خطأ في الخادم الداخلي