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 هناك عدد كبير جدًا من الطلبات
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 في الخادم الداخلي