תגובות לשגיאות

כשבקשת API מצליחה, ה-API מחזיר קוד סטטוס 200 OK יחד עם הנתונים המבוקשים בגוף התגובה. אם מתרחשת שגיאה, ה-API מחזיר אחד מקודי השגיאה הקנוניים שהוגדרו על ידי Google APIs, שמופה לקוד סטטוס של HTTP, וגוף תגובה שמכיל מידע על השגיאה. אם נתקלים בשגיאה, בודקים את השדות message ו-status בגוף התגובה של ה-JSON כדי לקבל פרטים ספציפיים שיעזרו בניפוי הבאגים.

פורמט השגיאה

אם בקשה מסוימת גורמת לשגיאה, ה-API מחזיר קוד סטטוס מתאים של HTTP וגוף תגובה בפורמט JSON. תגובת השגיאה מכילה אובייקט error עם המבנה הבא:

{
  "error": {
    "code": 403,
    "message": "User does not have sufficient permissions for this property.",
    "status": "PERMISSION_DENIED"
  }
}

אובייקט error מכיל את השדות הבאים:

שדה	תיאור
קוד	קוד סטטוס של HTTP, כמו 400,‏ 401,‏ 403,‏ 429 או 500.
message	תיאור קצר של השגיאה.
סטטוס	קוד השגיאה הקנוני, כמו INVALID_ARGUMENT,‏ UNAUTHENTICATED,‏ PERMISSION_DENIED,‏ RESOURCE_EXHAUSTED או INTERNAL.

שגיאות נפוצות

בטבלה הבאה מפורטות שגיאות נפוצות שמוחזרות על ידי ה-API.

קוד סטטוס של HTTP	קוד קנוני	סיבה	תיאור
400	INVALID_ARGUMENT	בקשה פגומה	הפורמט של הבקשה שגוי. הסיבה לכך יכולה להיות פרמטרים חסרים או לא תקינים, כמו טווח תאריכים שגוי או מסנן בפורמט שגוי.
401	UNAUTHENTICATED	פרטי כניסה לא חוקיים	בבקשה לא צוינו פרטי כניסה תקינים לאימות של משאב היעד. הבעיה הזו יכולה לקרות אם אסימון הגישה מסוג OAuth 2.0 חסר, לא חוקי או שתוקפו פג. פועלים לפי ההוראות במאמר אימות באמצעות OAuth 2.0 כדי לקבל אסימון תקף.
403	PERMISSION_DENIED	הרשאות לא מספיקות	למשתמש המאומת אין גישה לנכס ב-Google Analytics המבוקש.
429	RESOURCE_EXHAUSTED	חריגה מהמכסה	הבקשה נדחתה כי הגעתם למגבלות המכסה של ה-API. מידע נוסף זמין במאמר בנושא מכסות ומגבלות של Data API. יכול להיות שחרגתם מהמגבלות לכל פרויקט או לכל נכס.
500	INTERNAL	שגיאת שרת פנימית	קרתה שגיאה לא צפויה בחיבור לשרת. בדרך כלל מדובר בבעיה זמנית. מומלץ לנסות לשלוח שוב את הבקשה עם השהיה מעריכית לפני ניסיון חוזר. כדי לא לחרוג ממכסות שגיאות השרת, חשוב להטמיע השהיה מעריכית לפני ניסיון חוזר עם מגבלות על מספר הניסיונות החוזרים.
503	UNAVAILABLE	השירות לא זמין	השירות לא זמין כרגע. בדרך כלל מדובר בבעיה זמנית. מומלץ לנסות לשלוח שוב את הבקשה עם השהיה מעריכית לפני ניסיון חוזר. כדי לא לחרוג ממכסות שגיאות השרת, חשוב להטמיע השהיה מעריכית לפני ניסיון חוזר עם מגבלות על מספר הניסיונות החוזרים.