Code
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
קודי שגיאה קנוניים לממשקי API של gRPC.
לפעמים ייתכן שיופיעו כמה קודי שגיאה. השירותים צריכים להחזיר את קוד השגיאה הספציפי ביותר שרלוונטי. לדוגמה, עדיף OUT_OF_RANGE על FAILED_PRECONDITION אם שני הקודים חלים. באופן דומה, עדיף NOT_FOUND או ALREADY_EXISTS על פני FAILED_PRECONDITION.
| טיפוסים בני מנייה (enum) |
OK |
לא שגיאה. הוחזרה בהצלחה. מיפוי HTTP: 200 תקין |
CANCELLED |
הפעולה בוטלה, לרוב על ידי המתקשר. מיפוי HTTP: בקשה סגורה ללקוח מסוג 499 |
UNKNOWN |
שגיאה לא ידועה. לדוגמה, ייתכן שהשגיאה הזו תופיע אם ערך Status שהתקבל ממרחב כתובות אחר שייך למרחב שגיאה שלא ידוע במרחב הכתובות הזה. בנוסף, ייתכן שהשגיאה תוחזר לשגיאות שהועלו על ידי ממשקי API שלא מחזירים מספיק מידע על השגיאות. מיפוי 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 אם הלקוח צריך לנסות שוב ברמה גבוהה יותר. לדוגמה, כשבדיקה והגדרה שהוגדרו על ידי לקוח נכשלות, צריך לציין שהלקוח צריך להפעיל מחדש רצף קריאה-שינוי-כתיבה. (ג) יש להשתמש ב-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 |
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2023-06-08 (שעון UTC).
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 2023-06-08 (שעון UTC)."],[[["This documentation outlines the canonical error codes for gRPC APIs, providing a standardized way to handle and interpret errors across different services."],["Each error code has a specific meaning and an associated HTTP mapping for easier integration with existing web infrastructure."],["Services should prioritize returning the most specific error code applicable to a given situation, aiding in accurate diagnosis and troubleshooting."],["The error codes cover a wide range of scenarios, including client errors, server errors, and resource constraints, ensuring comprehensive error handling."],["While some errors may be transient and recoverable through retries, others indicate more serious issues requiring system-level intervention."]]],["gRPC APIs use specific error codes to indicate the outcome of operations. Services should return the most relevant code when multiple codes apply. Codes include `OK` for success and various error types like `CANCELLED`, `UNKNOWN`, `INVALID_ARGUMENT`, `NOT_FOUND`, `PERMISSION_DENIED`, `RESOURCE_EXHAUSTED`, and `UNAVAILABLE`. Others, such as `FAILED_PRECONDITION`, `ABORTED`, and `OUT_OF_RANGE` are used for state-related issues. Each code also has a corresponding HTTP mapping for error communication.\n"]]
