Code

کدهای خطای متعارف برای API های gRPC.

گاهی اوقات ممکن است چندین کد خطا اعمال شود. سرویس‌ها باید خاص‌ترین کد خطایی که اعمال می‌شود را برگردانند. برای مثال، اگر هر دو کد اعمال می‌شوند، OUT_OF_RANGE به FAILED_PRECONDITION ترجیح دهید. به طور مشابه NOT_FOUND یا ALREADY_EXISTS را به FAILED_PRECONDITION ترجیح دهید.

انوم‌ها
OK	خطا نیست؛ در صورت موفقیت برگردانده می‌شود. نگاشت HTTP: 200 OK
CANCELLED	عملیات، معمولاً توسط تماس‌گیرنده، لغو می‌شد. نگاشت HTTP: درخواست بسته شده کلاینت ۴۹۹
UNKNOWN	خطای ناشناخته. برای مثال، این خطا ممکن است زمانی برگردانده شود که مقدار Status دریافت شده از فضای آدرس دیگری متعلق به فضای خطایی باشد که در این فضای آدرس شناخته شده نیست. همچنین خطاهای ایجاد شده توسط API هایی که اطلاعات خطای کافی را برنمی گردانند، ممکن است به این خطا تبدیل شوند. نگاشت HTTP: خطای ۵۰۰ سرور داخلی
INVALID_ARGUMENT	کلاینت یک آرگومان نامعتبر مشخص کرده است. توجه داشته باشید که این با FAILED_PRECONDITION متفاوت است. INVALID_ARGUMENT نشان دهنده آرگومان‌هایی است که صرف نظر از وضعیت سیستم، مشکل‌ساز هستند (مثلاً نام فایل ناقص). نگاشت HTTP: درخواست نامناسب ۴۰۰
DEADLINE_EXCEEDED	مهلت قبل از اتمام عملیات به پایان رسیده است. برای عملیاتی که وضعیت سیستم را تغییر می‌دهند، این خطا ممکن است حتی اگر عملیات با موفقیت انجام شده باشد، بازگردانده شود. به عنوان مثال، پاسخ موفقیت‌آمیز از سرور می‌تواند به اندازه کافی به تأخیر بیفتد تا مهلت منقضی شود. نگاشت HTTP: زمان انتظار دروازه ۵۰۴
NOT_FOUND	برخی از موجودیت‌های درخواستی (مثلاً فایل یا دایرکتوری) یافت نشد. نکته برای توسعه‌دهندگان سرور: اگر درخواستی برای کل یک کلاس از کاربران رد شود، مانند انتشار تدریجی ویژگی یا لیست دسترسی‌های بدون سند، می‌توان از NOT_FOUND استفاده کرد. اگر درخواستی برای برخی از کاربران در یک کلاس از کاربران رد شود، مانند کنترل دسترسی مبتنی بر کاربر، باید PERMISSION_DENIED استفاده شود. نگاشت HTTP: خطای ۴۰۴ یافت نشد
ALREADY_EXISTS	موجودیتی که کلاینت سعی در ایجاد آن داشته است (مثلاً فایل یا دایرکتوری) از قبل وجود دارد. نگاشت HTTP: تداخل ۴۰۹
PERMISSION_DENIED	فراخواننده مجوز اجرای عملیات مشخص شده را ندارد. PERMISSION_DENIED نباید برای رد شدن‌های ناشی از اتمام منابع استفاده شود (به جای آن برای این خطاها RESOURCE_EXHAUSTED استفاده کنید). PERMISSION_DENIED نباید در صورتی که فراخواننده قابل شناسایی نباشد استفاده شود (به جای آن برای این خطاها UNAUTHENTICATED استفاده کنید). این کد خطا به این معنی نیست که درخواست معتبر است یا موجودیت درخواست شده وجود دارد یا سایر پیش‌شرط‌ها را برآورده می‌کند. نگاشت HTTP: ۴۰۳ ممنوع
UNAUTHENTICATED	درخواست، اعتبارنامه‌های احراز هویت معتبری برای عملیات ندارد. نگاشت HTTP: خطای ۴۰۱ غیرمجاز
RESOURCE_EXHAUSTED	برخی از منابع به اتمام رسیده‌اند، شاید سهمیه هر کاربر، یا شاید کل سیستم فایل فضای کافی ندارد. نگاشت HTTP: درخواست‌های بسیار زیاد ۴۲۹
FAILED_PRECONDITION	این عملیات رد شد زیرا سیستم در حالت مورد نیاز برای اجرای عملیات نیست. برای مثال، دایرکتوری که قرار است حذف شود خالی نیست، عملیات rmdir روی یک دایرکتوری غیر از دایرکتوری اعمال می‌شود و غیره. پیاده‌سازی‌کنندگان سرویس می‌توانند از دستورالعمل‌های زیر برای تصمیم‌گیری بین FAILED_PRECONDITION ، ABORTED و UNAVAILABLE استفاده کنند: (الف) اگر کلاینت می‌تواند فقط فراخوانی ناموفق را دوباره امتحان کند، UNAVAILABLE استفاده کنید. (ب) اگر کلاینت باید در سطح بالاتری دوباره امتحان کند، ABORTED استفاده کنید. به عنوان مثال، هنگامی که یک تست و مجموعه مشخص شده توسط کلاینت با شکست مواجه می‌شود، نشان می‌دهد که کلاینت باید یک توالی خواندن-تغییر-نوشتن را مجدداً راه‌اندازی کند. (ج) اگر کلاینت نباید تا زمانی که وضعیت سیستم به طور صریح اصلاح نشده است، دوباره امتحان کند، FAILED_PRECONDITION استفاده کنید. به عنوان مثال، اگر "rmdir" به دلیل خالی نبودن دایرکتوری با شکست مواجه شود، FAILED_PRECONDITION باید برگردانده شود زیرا کلاینت نباید دوباره امتحان کند مگر اینکه فایل‌ها از دایرکتوری حذف شوند. نگاشت HTTP: درخواست نامناسب ۴۰۰
ABORTED	این عملیات معمولاً به دلیل یک مشکل همزمانی مانند خرابی بررسی ترتیب‌سنج یا لغو تراکنش، لغو شد. برای تصمیم‌گیری بین FAILED_PRECONDITION ، ABORTED و UNAVAILABLE به دستورالعمل‌های بالا مراجعه کنید. نگاشت HTTP: تداخل ۴۰۹
OUT_OF_RANGE	این عملیات فراتر از محدوده‌ی معتبر انجام شده است. مثلاً جستجو یا خواندن فراتر از انتهای فایل. برخلاف INVALID_ARGUMENT ، این خطا نشان‌دهنده مشکلی است که در صورت تغییر وضعیت سیستم ممکن است برطرف شود. برای مثال، یک سیستم فایل ۳۲ بیتی اگر از آن خواسته شود که در یک آفست که در محدوده [0,2^32-1] نیست، بخواند INVALID_ARGUMENT تولید می‌کند، اما اگر از آن خواسته شود از یک آفست که بزرگتر از اندازه فعلی فایل است، بخواند OUT_OF_RANGE تولید می‌کند. بین FAILED_PRECONDITION و OUT_OF_RANGE همپوشانی نسبتاً زیادی وجود دارد. توصیه می‌کنیم هنگام اعمال OUT_OF_RANGE (خطای خاص‌تر) استفاده کنید تا فراخوانی‌کنندگانی که از طریق یک فاصله تکرار می‌کنند، بتوانند به راحتی به دنبال خطای OUT_OF_RANGE بگردند تا پس از اتمام کارشان آن را تشخیص دهند. نگاشت HTTP: درخواست نامناسب ۴۰۰
UNIMPLEMENTED	این عملیات در این سرویس پیاده‌سازی نشده یا پشتیبانی/فعال نشده است. نگاشت HTTP: خطای ۵۰۱ پیاده‌سازی نشده است
INTERNAL	خطاهای داخلی. این بدان معناست که برخی از ثابت‌های مورد انتظار سیستم اصلی، دچار مشکل شده‌اند. این کد خطا برای خطاهای جدی در نظر گرفته شده است. نگاشت HTTP: خطای ۵۰۰ سرور داخلی
UNAVAILABLE	سرویس در حال حاضر در دسترس نیست. این به احتمال زیاد یک وضعیت گذرا است که می‌توان با تلاش مجدد با یک backoff آن را اصلاح کرد. توجه داشته باشید که تلاش مجدد برای عملیات غیر خودتوان همیشه ایمن نیست. برای تصمیم‌گیری بین FAILED_PRECONDITION ، ABORTED و UNAVAILABLE به دستورالعمل‌های بالا مراجعه کنید. نگاشت HTTP: سرویس ۵۰۳ در دسترس نیست
DATA_LOSS	از دست رفتن یا خرابی غیرقابل بازیابی داده‌ها. نگاشت HTTP: خطای ۵۰۰ سرور داخلی