בדף הזה מתוארים קודי הסטטוס של HTTP והודעות השגיאה שמוחזרים על ידי BigQuery API. אתם יכולים להשתמש בקודים האלה כדי לפתור בעיות בבקשות שנכשלו, ולוודא שה-API פועל כמו שצריך.
מידע נוסף על שגיאות שאינן קשורות ל-API, שגיאות קישוריות של ספריית הלקוח ושגיאות במסוף Google Cloud זמין במאמר הודעות שגיאה.
למידע נוסף על שגיאות בשאילתות, קראו את המאמר פתרון בעיות בשאילתות.
למידע נוסף על שגיאות בהזנת זרם נתונים, ראו פתרון בעיות בהזנת זרם נתונים.
פורמט התגובה לשגיאה
ב-BigQuery נעשה שימוש בפורמט הסטנדרטי של דיווח על שגיאות HTTP ב-API. בקשות שהצליחו מחזירות קודי סטטוס של HTTP בטווח 2xx. בקשות שנכשלו מחזירות קודי סטטוס בטווחים 4xx ו-5xx. בקשות שדורשות הפניה אוטומטית מחזירות קודי סטטוס בטווח 3xx. תגובות שגיאה בדרך כלל כוללות מסמך JSON בגוף התגובה, שמכיל אובייקט שגיאה עם מידע על השגיאה.
בתגובות מה-API של BigQuery, אובייקט השגיאה הוא בדרך כלל אחד מהבאים:
- אובייקט
errors, שמכיל מערך של אובייקטים מסוגErrorProto. - אובייקט
errorResults, שמכיל אובייקטErrorProtoאחד.
העמודה סיבה בטבלאות של קודי הסטטוס בדף הזה ממופה למאפיין reason באובייקט ErrorProto. אם אתם משתמשים בכלי שורת הפקודה של BigQuery כדי לבדוק את סטטוס המשימה, השתמשו בדגל --format=prettyjson (לדוגמה, bq --format=prettyjson show -j <var>JOB_ID</var>) או בדגל --apilog=stdout כדי להציג את אובייקט השגיאה ואת המאפיין reason שלו.
בטבלה הבאה מתוארים הרכיבים שיכולים להופיע בגוף התגובה של שגיאה. כדי לזהות את הבעיה, צריך להשתמש בשדות ביחד. בנוסף, הערכים לדוגמה בטבלה הבאה נועדו להמחשה בלבד, והם לא רשימה ממצה של כל הערכים האפשריים.
| רכיב | תיאור |
|---|---|
code |
ערך של קוד סטטוס של HTTP, בלי התיאור הטקסטואלי. ערכים לדוגמה: 400 (בקשה שגויה), 403 (אסור) ו-404 (לא נמצא). |
error |
מאגר לפרטי השגיאה. |
errors |
מאגר לפרטי השגיאה. |
שגיאות.domain |
היקף השגיאה. ערכים לדוגמה: global ו-usageLimits. |
שגיאות.location |
הפריט הספציפי בתוך locationType שגרם לשגיאה. לדוגמה, אם מציינים ערך לא חוקי לפרמטר, הערך של location יהיה שם הפרמטר.ערכים לדוגמה: Authorization ו-project. |
שגיאות.locationType |
המיקום או החלק בבקשה שגרמו לשגיאה. אפשר להשתמש בפרמטר הזה עם location כדי לאתר את השגיאה.ערכים לדוגמה: header ו-parameter. |
שגיאות.message |
תיאור השגיאה. ערכים לדוגמה: Invalid argument, Access Denied ו-Not Found: Dataset myproject:foo. |
שגיאות.reason |
מזהה ייחודי של הגורם לשגיאה. ערכים לדוגמה: invalid, accessDenied ו-notFound. |
message |
תיאור השגיאה. כמו בשגיאות.message. |
קודי סטטוס וקודי שגיאה של HTTP
בקטע הזה מופיעה רשימה חלקית של קודי סטטוס וקודי שגיאה של HTTP מ-BigQuery API. קודי המידע 1xx וקודי ההצלחה 2xx לא נכללים. מידע נוסף זמין בקודים של סטטוס תגובה ב-RFC 7231 §6, ב-RFC 7232 §4, ב-RFC 7233 §4, ב-RFC 7235 §3 וב-RFC 6585.
400 — בקשה לא תקינה
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
badRequest |
400 |
פקודת DML מנסה לשנות שורות שהועברו לאחרונה בסטרימינג באמצעות ה-API הקודם של |
עבור אל BigQuery Storage Write API (gRPC), המתן מספר דקות עד שמאגר הסטרימינג יתרוקן, או סנן את ההצהרה שלך כדי לא לכלול שורות שהוזרמות לאחרונה. מידע נוסף זמין במאמר הצהרות DML בטבלאות עם מאגר נתונים זמני (buffer) של סטרימינג. |
invalid |
400 |
הבקשה מכילה קלט לא חוקי, שהוא לא שאילתה לא חוקית, כולל המקרים הבאים:
|
צריך לוודא שהסכימות שסופקו תואמות לעמודות ולמצבים הקיימים, לשטח מבנים שחורגים מ-15 רמות של הטמעה (או לאחסן אותם כ- |
invalidQuery |
400 |
שאילתת SQL נכשלת בבדיקות האימות או ההרצה, מאחת מהסיבות הבאות:
|
צריך לבדוק את המיקום |
jobBackendError |
400 |
ב- |
מנסים שוב את המשימה עם |
jobInternalError |
400 |
ב- |
מנסים שוב את המשימה עם |
preconditionFailed |
400 |
תנאי מקדים של בקשה לא מתקיים, כולל במקרים הבאים:
|
אחזרו את המשאב הנוכחי |
resourceInUse |
400 |
בקשת מחיקה מטרגטת משאב שעדיין פעיל או מאוכלס:
השגיאה שמוחזרת: |
מרוקנים את קבוצת הנתונים לפני שמוחקים אותה (או מגדירים את |
resourcesExceeded |
400 |
משימה חורגת ממגבלות המשאבים לביצוע באחד מהתחומים הבאים:
השגיאה שמוחזרת: |
כדי לפתור את הבעיה, אפשר לפשט את השאילתות, לבצע פעולות DML בכמות גדולה, לצמצם את העמודות או המחיצות שנסרקות, להימנע מהפעלת משימות בו-זמנית באותו סשן או להקצות קיבולת ייעודית של משבצות לעומסי עבודה שכוללים הרבה פעולות ערבוב. כדי לראות את השלבים לכל סוג משנה, קראו את המאמרים פתרון בעיות של חריגה במשאבים והשאילתה חורגת ממשאבי הזיכרון. |
storageUnusable |
400 |
האחסון הפנימי של BigQuery שבו נמצאים נתוני הטבלה לא זמין באופן זמני בגלל בעיית אחסון בצד השירות. השגיאה שמוחזרת:
|
מנסים שוב להפעיל את המשימה באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff). מידע נוסף זמין במאמר לא ניתן להשתמש באחסון הטבלה. |
streamingDataUnavailable |
400 |
נתונים שהועברו לאחרונה בסטרימינג לאחסון שמותאם לכתיבה לא זמינים באופן זמני למשימת קריאה. השגיאה שמוחזרת: |
מנסים שוב להפעיל את המשימה עם |
tableUnavailable |
400 |
BigQuery לא יכול לקרוא טבלה שהנתונים שלה לא מנוהלים על ידו, כולל במקרים הבאים:
|
מנסים שוב לאחזר את הסכימה או את הזמן הקצוב לתפוגה של טבלת הגיבוי באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff), או מאמתים את נתיבי ה-URI של |
userOwnedResourceError |
400 |
משאב חיצוני שבבעלותכם מחזיר שגיאה כש-BigQuery ניגש אליו. השגיאה שמוחזרת: |
כדי לזהות את המשאב החיצוני, בודקים את resource_type ואת resource_name בהודעת השגיאה, ופותרים את השגיאה הבסיסית שדווחה ב-external_error. מידע נוסף מופיע בקטע שגיאה במשאב חיצוני בבעלות המשתמש. |
vortexDataUnavailable |
400 |
נתונים שהועברו לאחרונה באמצעות BigQuery Storage Write API (gRPC) לאחסון שמותאם לכתיבה, לא זמינים באופן זמני לשאילתה. השגיאה שמוחזרת: |
מנסים שוב את משימת השאילתה עם |
billingTierLimitExceeded |
400 |
שאילתה על פי דרישה חורגת ממגבלת השימוש המקסימלי במעבד (CPU) לנתונים שנסרקו. השגיאה שמוחזרת: |
משנים את קוד ה-SQL כדי להסיר מכפלות קרטזיות לא מכוונות, איחודים לא מדויקים, פונקציות אנליטיות לא מחולקות או פונקציות JavaScript UDF כבדות, או עוברים לתמחור מבוסס-קיבולת (משבצות). למידע נוסף, ראו השאילתה חורגת ממשאבי ה-CPU והימנעות מתבניות anti-SQL. |
bytesBilledLimitExceeded |
400 |
הערכת הגבול העליון של הבייטים לפני הרצת השאילתה חורגת מ- |
כדי להפחית את כמות הנתונים שעובדו, אפשר להציג תצוגה מקדימה של הבייטים המשוערים באמצעות הרצה יבשה, לבחור רק את העמודות הדרושות ולסנן לפי עמודות מחולקות למחיצות. אפשר גם להגדיל את |
jobRateLimitExceeded |
400 |
ב-
|
צמצמו את מספר השליחות בו-זמנית (או השתמשו בעדיפות של אצווה או בהתאמה אוטומטית לעומס של יחידות קיבולת לשאילתות מתמשכות), ונסו שוב את המשימה עם |
timeout |
400 |
פעולה חורגת ממגבלת זמן הביצוע שלה, כולל במקרים הבאים:
|
סננו עמודות מחולקות למחיצות או לאשכולות, ופצלו שאילתות מורכבות או שאילתות עם כמה הצהרות לשלבים קטנים יותר. לחלופין, ציינו סכימה מפורשת ומזהי URI צרים יותר של מקורות כשאתם יוצרים טבלאות חיצוניות. מידע נוסף זמין במאמרים השאילתה חורגת ממגבלת זמן הביצוע ופתרון שגיאות שקשורות למכסות ולמגבלות. |
invalidUser |
400 |
שאילתה מתוזמנת הוגדרה עם פרטי כניסה לא תקינים של משתמש. |
מרעננים את פרטי הכניסה של המשתמש לשאילתה המתוזמנת. מידע נוסף זמין במאמר תזמון שאילתות. |
required |
400 |
חסר קלט חובה לפני ההפעלה:
השגיאה שמוחזרת: |
בודקים את גוף הבקשה ואת הפרמטרים של השאילתה שנדרשים במאמרי העזרה של BigQuery API או במסמכי התיעוד של ספריית הלקוח, ובודקים את אובייקט ההגדרה לפני ששולחים קריאה ל-API. מידע נוסף זמין במאמר אחד מהפרמטרים הנדרשים חסר. |
401 – Unauthorized
הדוגמה הבאה היא תגובת שגיאה שמתקבלת אם הבקשה לא כוללת פרטי כניסה לאימות תקינים.
401 Unauthorized
{
"error": {
"errors": [
{
"domain": "global",
"reason": "unauthenticated",
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential."
}
],
"code": 401,
"message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.",
"status": "UNAUTHENTICATED"
}
}
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
unauthenticated |
401 |
אימות הבקשה נכשל בגלל אחת מהסיבות הבאות:
|
צריך לרענן את פרטי הכניסה שמוגדרים כברירת מחדל של OAuth או של Application Default Credentials, לתת את ההרשאה |
403 — Forbidden
זו דוגמה לתגובת שגיאה שתקבלו אם אין לכם הרשאת גישה למשאב המבוקש.
403 Forbidden
{
"error": {
"errors": [
{
"domain": "global",
"reason": "accessDenied",
"message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
}
],
"code": 403,
"message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
}
}
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
responseTooLarge |
403 |
תגובה לקריאה של שאילתה או טבלה חורגת ממגבלות הגודל באחת מהדרכים הבאות:
השגיאה שמוחזרת: |
מציינים טבלת יעד (ומגדירים את |
apiLimitExceeded |
403 |
בקשה חורגת מאחת מהמגבלות הבאות של ה-API או של המטא-נתונים:
השגיאה שמוחזרת: |
נסו שוב לשלוח בקשות שנכשלו באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff), טעינות וקריאות באצווה, פשטו את כללי המדיניות של IAM ברמת הטבלה או את כללי המדיניות של אבטחה ברמת השורה, והמתינו לחלון הזמן הדינמי לפני שתוסיפו רפליקות של מערכי נתונים. למידע נוסף, קראו את המאמרים שגיאות שקשורות למגבלות על קצב ה-API והערכת המטא-נתונים ושגיאות שקשורות למגבלות על יצירת רפליקות של מערכי נתונים באזורים שונים. |
quotaExceeded |
403 |
הפרויקט חורג מאחת ממכסות השימוש הבאות:
השגיאה שמוחזרת: |
בודקים את השגיאה |
rateLimitExceeded |
403 |
בקשה נדחית בגלל אחת ממגבלות הקצב או הבו-זמניות הבאות:
|
להאט את קצב הבקשות ולנסות שוב באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff), או להריץ שאילתות לא דחופות עם עדיפות באצווה ולהתאים את ההתאמה האוטומטית לעומס של ה-slots או את ההקצאה בו-זמנית של ההזמנות. למידע נוסף, קראו את המאמרים פתרון בעיות שקשורות לשגיאות במכסות ובמגבלות ודחיית בקשות לשאילתות. |
accessDenied |
403 |
הגישה למשאב BigQuery נדחתה מאחת מהסיבות הבאות:
השגיאה שמוחזרת: |
בודקים את יומני הביקורת של Cloud ( |
policyViolation |
403 |
הבקשה נחסמת על ידי מדיניות הארגון או היקף אבטחה:
|
מסננים את ה-Logs Explorer לפי |
billingNotEnabled |
403 |
בפרויקט אין חיוב פעיל לפעולה המבוקשת:
השגיאה שמוחזרת: |
מפעילים את החיוב בפרויקט במסוףGoogle Cloud כדי לשדרג מארגז החול של BigQuery, ואז מעדכנים את זמני התפוגה שמוגדרים כברירת מחדל לטבלאות, לתצוגות ולמחיצות. מידע נוסף זמין במאמר החיוב לא מופעל בפרויקט. |
blocked |
403 |
BigQuery הוסיף באופן זמני את הפעולה שניסיתם לבצע לרשימת ישויות שנחסמו כדי למנוע הפסקה זמנית בשירות. השגיאה שמוחזרת: |
פנו ל-Cloud Customer Care וציינו את חותמת הזמן המדויקת, מזהה הפרויקט ומזהה המשימה ב-BigQuery כדי לבדוק את כלל ההפחתה הניהולי. מידע נוסף זמין במאמר הבקשה נחסמה כדי להגן על פעולת המערכת. |
termsOfServiceNotAccepted |
403 |
הפרויקט לא אישר את התנאים וההגבלות של BigQuery. השגיאה שמוחזרת: |
נכנסים למסוףGoogle Cloud , בוחרים את המדינה ומסמנים את תיבת הסימון של התנאים וההגבלות בדף קבלת הפנים, אם מוצגת בקשה לעשות זאת, ולוחצים על Agree and continue. למידע נוסף, קראו את המאמר התנאים וההגבלות של BigQuery לא אושרו. |
404 – לא נמצא
הדוגמה הבאה היא תגובת שגיאה שמתקבלת כשמנסים לאחזר מערך נתונים או משאב שלא קיימים.
404 Not Found
{
"error": {
"errors": [
{
"domain": "global",
"reason": "notFound",
"message": "Not Found: Dataset myproject:foo"
}
],
"code": 404,
"message": "Not Found: Dataset myproject:foo"
}
}
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
notFound |
404 |
לא ניתן למצוא את המשאב המבוקש בגלל אחת מהסיבות הבאות:
השגיאה שמוחזרת: |
צריך לוודא שהמיקום והמזהה של הפרויקט, מערך הנתונים והטבלה מדויקים ותלויי אותיות רישיות, לשחזר טבלאות שנמחקו בחלון הזמן של הנסיעה בזמן, להריץ מחדש שאילתות שטבלאות התוצאות שלהן במטמון פג תוקף, או לוודא שקיימים קבצים חיצוניים ב-Cloud Storage או ב-Google Drive. למידע נוסף, קראו את המאמרים Table not found, Location not found ו-Job not found. |
409 — Conflict
הדוגמה הבאה היא של תגובת שגיאה שמתקבלת כשמנסים ליצור משאב שכבר קיים.
409 Conflict
{
"error": {
"errors": [
{
"domain": "global",
"reason": "duplicate",
"message": "Already Exists: Dataset myproject:mydataset"
}
],
"code": 409,
"message": "Already Exists: Dataset myproject:mydataset"
}
}
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
abortd |
409 |
פעולה נעצרת בגלל שינוי בו-זמני או התנגשות (מוחזרת עם הסיבה |
נסו שוב את הפעולה אחרי שהפעולה המתנגשת תסתיים באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (exponential backoff), או החזירו למצב הקודם טרנזקציות מרובות-הצהרות שהופסקו לפני הניסיון החוזר. הפעולה בוטלה |
duplicate |
409 |
בקשה מתנגשת עם משאב קיים באחת מהדרכים הבאות:
השגיאה שמוחזרת: |
צריך להשתמש בשם משאב אחר, להשתמש ב- |
499 – הלקוח סגר את הבקשה
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
stopped |
499 |
משימה נעצרת לפני שהיא מסתיימת בגלל אחת מהסיבות הבאות (הסקר
השגיאה שמוחזרת: |
מגדילים את אפשרויות הזמן הקצוב לתפוגה של |
500 – שגיאת שרת פנימית
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
internalError |
500 |
אירעה שגיאה פנימית ב-BigQuery. השגיאה שמוחזרת:
|
ממתינים בהתאם לדרישות ההשהיה לפני ניסיון חוזר (backoff) שמפורטות בהסכם רמת השירות של BigQuery, ומנסים שוב באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff). אפשר גם להשתמש בהזמנות כדי להפחית את התדירות של שגיאות זמניות. מידע נוסף זמין במאמר פתרון בעיות שקשורות לשגיאות internalError. |
501 — לא בוצע יישום
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
notImplemented |
501 |
בקשה שמנסה להשתמש בתכונה או בפעולה שלא הוטמעו במשאב היעד, למשל:
השגיאה שמוחזרת: |
צריך להמיר מקורות לא נתמכים של העתקת טבלאות באמצעות |
503 – השירות לא זמין
| סיבה | קוד סטטוס של HTTP | תיאור | פתרון בעיות |
|---|---|---|---|
backendError |
503 |
השירות לא זמין כרגע בגלל אחת מהסיבות הבאות:
השגיאה שמוחזרת: |
מנסים שוב לשלוח את הבקשות באמצעות השהיה מעריכית קטועה לפני ניסיון חוזר (truncated exponential backoff), ומנסים שוב להפעיל את המשימות שנכשלו עם |