خطاهای API را مدیریت کنید

وقتی درخواستی را به API گوگل ادز ارسال می‌کنید، ممکن است به دلایل مختلف با شکست مواجه شود. به عنوان مثال، ممکن است یک آرگومان نامعتبر ارائه دهید، یا ممکن است حساب شما به محدودیت خود برای ایجاد کمپین‌های جدید رسیده باشد. در چنین مواردی، API خطایی را برمی‌گرداند تا به شما اطلاع دهد که چه مشکلی پیش آمده است.

این راهنما نحوه خواندن و مدیریت خطاهای API را توضیح می‌دهد تا بتوانید برنامه‌های قوی‌تری بسازید.

ساختار خطا

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

API گوگل ادز اطلاعات خطا را در قالبی استاندارد برمی‌گرداند. اگر خطایی رخ دهد، پاسخ شامل یک شیء GoogleAdsFailure خواهد بود. این شیء شامل فهرستی از اشیاء GoogleAdsError است که هر کدام جزئیات یک خطای خاص را شرح می‌دهند.

هر شیء GoogleAdsError موارد زیر را ارائه می‌دهد:

• error_code : یک کد خطای خاص که نوع خطا را به شما می‌گوید، مانند AuthenticationError.NOT_ADS_USER .
• message : توضیحی خوانا برای انسان در مورد دلیل وقوع خطا.
• trigger : مقداری که باعث خطا شده است، مانند "1234".
• location : جزئیاتی در مورد اینکه کدام بخش از درخواست باعث خطا شده است، مانند نام یک فیلد خاص.

علاوه بر لیست خطاها، GoogleAdsFailure شامل یک requestId است که یک شناسه منحصر به فرد برای درخواست API است که منجر به خطا شده است.

خطای مثال

در اینجا مثالی از چگونگی نمایش یک خطا در قالب JSON آورده شده است. این خطا نشان می‌دهد که فیلد name ad_group در اندیس 0 در درخواست وجود ندارد.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

نحوه مدیریت خطاها

اگر با خطایی مواجه شدید، مراحل زیر را دنبال کنید:

1. لیست errors را بررسی کنید : به هر GoogleAdsError در شیء GoogleAdsFailure نگاه کنید. error_code و message به شما می‌گویند که چه مشکلی پیش آمده است.
2. location را بررسی کنید : فیلد location می‌تواند به شما کمک کند تا مشخص کنید مشکل در کجای درخواست شما رخ داده است.
3. به مستندات مراجعه کنید : برای کدهای خطای خاص، صفحه خطاهای رایج یا مرجع کامل کد خطا را برای جزئیات بیشتر در مورد خطا و نحوه رفع آن بررسی کنید.
4. درخواست خود را تنظیم کنید : بر اساس پیام خطا، درخواست API خود را اصلاح کنید. برای مثال، اگر REQUIRED_FIELD_MISSING را مشاهده کردید، مطمئن شوید که آن فیلد را در درخواست خود ارائه می‌دهید.
5. شناسه request_id را وارد کنید : اگر نمی‌توانید بفهمید چگونه یک خطا را حل کنید و نیاز دارید از طریق انجمن با پشتیبانی تماس بگیرید، request_id وارد کنید. این شناسه به مهندسان گوگل کمک می‌کند تا مشکل شما را بررسی کنند.

مراحل بعدی

• برای فهرستی از مشکلات رایج و راه‌حل‌های آنها ، خطاهای رایج را مرور کنید.
• برای تکنیک‌های پیشرفته‌تر مدیریت خطا، از جمله منطق تلاش مجدد و شکست جزئی، به بخش «درک خطاهای API» مراجعه کنید.