Code

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

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

عمليات التعداد
OK	ليس خطأ، بل يتم عرضه عند النجاح. ربط HTTP: 200 OK
CANCELLED	تم إلغاء العملية، وعادةً ما يكون ذلك من قِبل المتصل. ربط HTTP: 499 Client Closed Request
UNKNOWN	حدث خطأ غير معروف. على سبيل المثال، قد يتم عرض هذا الخطأ عندما تنتمي قيمة Status تم تلقّيها من مساحة عناوين أخرى إلى مساحة أخطاء غير معروفة في مساحة العناوين هذه. قد يتم أيضًا تحويل الأخطاء التي تظهر في واجهات برمجة التطبيقات التي لا تعرض معلومات كافية عن الخطأ إلى هذا الخطأ. ربط HTTP: 500 Internal Server Error
INVALID_ARGUMENT	حدّد العميل وسيطة غير صالحة. يُرجى العلم أنّ هذا يختلف عن FAILED_PRECONDITION. يشير INVALID_ARGUMENT إلى الوسيطات التي تسبّب مشاكل بغض النظر عن حالة النظام (مثل اسم ملف غير صالح). ربط HTTP: طلب غير صالح (400)
DEADLINE_EXCEEDED	انتهت المهلة قبل أن تتمكّن العملية من الاكتمال. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى إذا اكتملت العملية بنجاح. على سبيل المثال، قد يتأخر الردّ الناجح من الخادم لفترة طويلة بما يكفي لانتهاء الموعد النهائي. ربط HTTP: انتهت مهلة البوابة 504
NOT_FOUND	لم يتم العثور على بعض الكيانات المطلوبة (مثل ملف أو دليل). ملاحظة لمطوّري الخادم: إذا تم رفض طلب لفئة كاملة من المستخدمين، مثل طرح الميزات تدريجيًا أو قائمة السماح غير الموثّقة، يمكن استخدام NOT_FOUND. في حال تم رفض طلب بعض المستخدمين ضمن فئة من المستخدمين، مثل التحكّم في الوصول المستند إلى المستخدم، يجب استخدام PERMISSION_DENIED. تعيين HTTP: لم يتم العثور على الصفحة (404)
ALREADY_EXISTS	الكيان الذي حاول العميل إنشاءه (مثل ملف أو دليل) متوفّر مسبقًا. ربط HTTP: 409 Conflict
PERMISSION_DENIED	ليس لدى المتصل إذن لتنفيذ العملية المحدّدة. يجب عدم استخدام PERMISSION_DENIED للرفض الناتج عن استنفاد بعض الموارد (استخدِم RESOURCE_EXHAUSTED بدلاً من ذلك لهذه الأخطاء). يجب عدم استخدام PERMISSION_DENIED إذا تعذّر تحديد هوية المتصل (استخدِم UNAUTHENTICATED بدلاً من ذلك لهذه الأخطاء). لا يعني رمز الخطأ هذا أنّ الطلب صالح أو أنّ العنصر المطلوب متوفّر أو يستوفي شروطًا مسبقة أخرى. تعيين HTTP: 403 Forbidden
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 Conflict
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 Internal Server Error
UNAVAILABLE	هذه الخدمة غير متاحة حاليًا. من المرجّح أنّ هذه حالة عابرة يمكن تصحيحها من خلال إعادة المحاولة مع التراجع. يُرجى العِلم أنّه ليس من الآمن دائمًا إعادة محاولة تنفيذ العمليات غير المتكرّرة. اطّلِع على الإرشادات أعلاه لتحديد ما إذا كان يجب استخدام FAILED_PRECONDITION أو ABORTED أو UNAVAILABLE. ربط HTTP: خطأ 503: الخدمة غير متاحة
DATA_LOSS	ثمة بيانات تالفة أو بيانات مفقودة ويتعذّر استرجاعها. ربط HTTP: 500 Internal Server Error