پاسخ های خطا

وقتی یک درخواست API با موفقیت انجام شود، API یک کد وضعیت 200 OK را به همراه داده‌های درخواستی در بدنه پاسخ برمی‌گرداند. اگر خطایی رخ دهد، API یکی از کدهای خطای متعارف تعریف شده توسط APIهای گوگل را که به یک کد وضعیت 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، مانند ۴۰۰، ۴۰۱، ۴۰۳، ۴۲۹ ​​یا ۵۰۰.
پیام	شرح مختصری از خطا.
وضعیت	کد خطای متعارف، مانند INVALID_ARGUMENT ، UNAUTHENTICATED ، PERMISSION_DENIED ، RESOURCE_EXHAUSTED یا INTERNAL .

خطاهای رایج

جدول زیر خطاهای رایجی را که توسط API برگردانده می‌شوند، فهرست می‌کند.

کد وضعیت HTTP	کد متعارف	دلیل	توضیحات
۴۰۰	INVALID_ARGUMENT	درخواست بد	درخواست ناقص است. این می‌تواند ناشی از پارامترهای نامعتبر یا از دست رفته، مانند محدوده تاریخ نادرست یا فیلتر ناقص باشد.
۴۰۱	UNAUTHENTICATED	اعتبارنامه‌های نامعتبر	درخواست، اعتبارنامه‌های احراز هویت معتبری برای منبع هدف ندارد. این اتفاق می‌تواند در صورتی رخ دهد که توکن دسترسی OAuth 2.0 وجود نداشته باشد، نامعتبر باشد یا منقضی شده باشد. برای دریافت توکن معتبر، دستورالعمل‌های موجود در بخش احراز هویت با OAuth 2.0 را دنبال کنید.
۴۰۳	PERMISSION_DENIED	مجوزهای ناکافی	کاربر احراز هویت شده به ویژگی درخواستی گوگل آنالیتیکس دسترسی ندارد.
۴۲۹	RESOURCE_EXHAUSTED	سهمیه تجاوز شد	درخواست به دلیل رسیدن به سقف سهمیه API رد شد. برای اطلاعات بیشتر به بخش محدودیت‌ها و سهمیه‌های Data API مراجعه کنید. ممکن است از سقف سهمیه هر پروژه یا هر ملک تجاوز کرده باشید.
۵۰۰	INTERNAL	خطای سرور داخلی	یک خطای غیرمنتظره در سرور رخ داده است. این معمولاً یک مشکل موقتی است. تلاش مجدد برای درخواست با backoff نمایی توصیه می‌شود. برای جلوگیری از تجاوز از سهمیه خطای سرور ، پیاده‌سازی backoff نمایی با محدودیت‌های تلاش مجدد مهم است.
۵۰۳	UNAVAILABLE	سرویس در دسترس نیست	سرویس موقتاً در دسترس نیست. این معمولاً یک مشکل موقتی است. تلاش مجدد برای درخواست با backoff نمایی توصیه می‌شود. برای جلوگیری از تجاوز از سهمیه خطای سرور ، پیاده‌سازی backoff نمایی با محدودیت‌های تلاش مجدد مهم است.