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

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

API تبلیغات گوگل از مدل خطای استاندارد API گوگل پیروی می‌کند که مبتنی بر کدهای وضعیت gRPC است. هر پاسخ API که منجر به خطا می‌شود شامل یک شیء Status است که شامل موارد زیر است:

  • یک کد خطای عددی.
  • یک پیام خطا.
  • جزئیات خطای اضافی و اختیاری.

کدهای خطای متعارف

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

جدول زیر خلاصه‌ای از رایج‌ترین کدهایی است که ممکن است هنگام استفاده از API گوگل ادز با آنها مواجه شوید:

کد gRPC کد HTTP نام شمارشی توضیحات راهنمایی
0 ۲۰۰ OK بدون خطا؛ نشان دهنده موفقیت است. ناموجود
۱ ۴۹۹ CANCELLED عملیات، معمولاً توسط مشتری، لغو شده است. معمولاً به این معنی است که کلاینت دیگر منتظر نمانده است. وقفه‌های زمانی سمت کلاینت را بررسی کنید.
۲ ۵۰۰ UNKNOWN خطای ناشناخته‌ای رخ داده است. جزئیات بیشتر ممکن است در پیام خطا یا جزئیات آن باشد. به عنوان یک خطای سرور در نظر گرفته شود. اغلب می‌توان با backoff دوباره امتحان کرد.
۳ ۴۰۰ INVALID_ARGUMENT کلاینت یک آرگومان نامعتبر مشخص کرده است. این نشان دهنده مشکلی است که مانع از پردازش درخواست توسط API می‌شود، مانند نام منبع نادرست یا مقدار نامعتبر. خطای کلاینت: پارامترهای درخواست خود را بررسی کنید و مطمئن شوید که الزامات API را برآورده می‌کنند. جزئیات خطا معمولاً اطلاعاتی در مورد اینکه کدام آرگومان نامعتبر بوده و چگونه - از این جزئیات برای رفع مشکل درخواست استفاده کنید، ارائه می‌دهد. بدون رفع مشکل درخواست، دوباره تلاش نکنید.
۴ ۵۰۴ DEADLINE_EXCEEDED مهلت قبل از اتمام عملیات به پایان رسید. خطای سرور: اغلب گذرا. تلاش مجدد با backoff نمایی را در نظر بگیرید.
۵ ۴۰۴ NOT_FOUND برخی از موجودیت‌های درخواستی، مانند یک کمپین یا گروه تبلیغاتی، یافت نشدند. خطای کلاینت: وجود و شناسه منابعی که می‌خواهید به آنها دسترسی پیدا کنید را تأیید کنید. بدون اصلاح دوباره امتحان نکنید.
۶ ۴۰۹ ALREADY_EXISTS موجودیتی که کلاینت سعی در ایجاد آن داشته، از قبل وجود دارد. خطای کلاینت: از ایجاد منابع تکراری خودداری کنید. قبل از تلاش برای ایجاد منبع، بررسی کنید که آیا منبع وجود دارد یا خیر.
۷ ۴۰۳ PERMISSION_DENIED فراخواننده مجوز اجرای عملیات مشخص شده را ندارد. خطای کلاینت: احراز هویت ، مجوزها و نقش‌های کاربری حساب گوگل ادز را بررسی کنید. بدون بررسی مجوزها دوباره امتحان نکنید.
۸ ۴۲۹ RESOURCE_EXHAUSTED یا یک منبع به اتمام رسیده است (برای مثال، شما از سهمیه خود فراتر رفته‌اید)، یا سیستم بیش از حد بارگذاری شده است. خطای کلاینت/سرور: معمولاً نیاز به انتظار دارد. backoff تصاعدی را پیاده‌سازی کنید و به طور بالقوه نرخ درخواست را کاهش دهید. به محدودیت‌ها و سهمیه‌های API مراجعه کنید.
۹ ۴۰۰ FAILED_PRECONDITION این عملیات رد شد زیرا سیستم در حالت مورد نیاز برای اجرای عملیات نیست. برای مثال، یک فیلد الزامی وجود ندارد. خطای کلاینت: درخواست معتبر است، اما وضعیت (state) اشتباه است. جزئیات خطا را بررسی کنید تا دلیل شکست پیش‌شرط را بفهمید. بدون اصلاح وضعیت، دوباره تلاش نکنید.
۱۰ ۴۰۹ ABORTED این عملیات معمولاً به دلیل یک مشکل همزمانی مانند تداخل تراکنش، لغو شده است. خطای سرور: اغلب با یک وقفه کوتاه، امتحان مجدد بی‌خطر است.
۱۱ ۴۰۰ OUT_OF_RANGE این عملیات فراتر از محدوده معتبر انجام شد. خطای کلاینت: محدوده یا اندیس را اصلاح کنید.
۱۲ ۵۰۱ UNIMPLEMENTED این عملیات توسط API پیاده‌سازی یا پشتیبانی نمی‌شود. خطای کلاینت: نسخه API و ویژگی‌های موجود را بررسی کنید. دوباره امتحان نکنید.
۱۳ ۵۰۰ INTERNAL یک خطای داخلی رخ داده است. این یک مشکل کلی برای مشکلات سمت سرور است. خطای سرور: معمولاً با backoff نمایی قابل امتحان مجدد است. در صورت تداوم، مشکل را گزارش دهید .
۱۴ ۵۰۳ UNAVAILABLE سرویس در حال حاضر در دسترس نیست. این احتمالاً یک وضعیت گذرا است. خطای سرور: اکیداً توصیه می‌شود با استفاده از روش برگشت نمایی (exponential backoff) دوباره امتحان کنید.
۱۵ ۵۰۰ DATA_LOSS از دست رفتن یا خرابی غیرقابل بازیابی داده‌ها. خطای سرور: نادر. نشان دهنده یک مشکل جدی است. دوباره امتحان نکنید. در صورت ادامه، مشکل را گزارش دهید .
۱۶ ۴۰۱ UNAUTHENTICATED درخواست فاقد اعتبارنامه احراز هویت معتبر است. خطای کلاینت: توکن‌ها و اعتبارنامه‌های احراز هویت خود را تأیید کنید. بدون رفع مشکل احراز هویت، دوباره امتحان نکنید.

برای جزئیات بیشتر در مورد این کدها، به راهنمای طراحی API - کدهای خطا مراجعه کنید.

جزئیات خطا را درک کنید

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

هر شیء GoogleAdsFailure شامل موارد زیر است:

  • errors : فهرستی از اشیاء GoogleAdsError که هر کدام جزئیات یک خطای خاص رخ داده را شرح می‌دهند.
  • request_id : یک شناسه منحصر به فرد برای درخواست، که برای اشکال‌زدایی و اهداف پشتیبانی مفید است.

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

مثالی از جزئیات خطا

وقتی خطایی دریافت می‌کنید، کتابخانه کلاینت شما به شما امکان دسترسی به این جزئیات را می‌دهد. برای مثال، یک INVALID_ARGUMENT (کد ۳) ممکن است جزئیات GoogleAdsFailure مانند این داشته باشد:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

در این مثال، علیرغم INVALID_ARGUMENT سطح بالا، جزئیات GoogleAdsFailure به شما می‌گوید که فیلدهای name و description باعث ایجاد مشکل شده‌اند و دلیل آن چیست (به ترتیب REQUIRED و TOO_SHORT ).

جزئیات خطا را پیدا کنید

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

فراخوانی‌های API استاندارد و استریمینگ

وقتی یک فراخوانی API بدون استفاده از خطای جزئی، از جمله فراخوانی‌های استریمینگ ، با شکست مواجه می‌شود، شیء GoogleAdsFailure به عنوان بخشی از فراداده‌های انتهایی در هدرهای پاسخ gRPC بازگردانده می‌شود. اگر از REST برای فراخوانی‌های استاندارد استفاده می‌کنید، GoogleAdsFailure در پاسخ HTTP بازگردانده می‌شود. کتابخانه‌های کلاینت معمولاً این مورد را به عنوان یک استثنا با ویژگی GoogleAdsFailure نمایش می‌دهند.

خرابی جزئی

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

کارهای دسته‌ای

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

درخواست شناسه

request-id یک رشته منحصر به فرد است که درخواست API شما را شناسایی می‌کند و برای عیب‌یابی ضروری است.

می‌توانید request-id را در چندین جا پیدا کنید:

  • GoogleAdsFailure : اگر فراخوانی API با شکست مواجه شود و GoogleAdsFailure بازگردانده شود، شامل یک request_id خواهد بود.
  • فراداده دنباله‌دار : برای هر دو درخواست موفق و ناموفق، request-id در فراداده دنباله‌دار پاسخ gRPC موجود است.
  • هدرهای پاسخ : برای درخواست‌های موفق و ناموفق، request-id نیز در هدرهای پاسخ gRPC و HTTP موجود است، به استثنای درخواست‌های پخش موفق.
  • SearchGoogleAdsStreamResponse : برای درخواست‌های پخش جریانی، هر پیام SearchGoogleAdsStreamResponse حاوی یک فیلد request_id است.

هنگام ثبت خطاها یا تماس با پشتیبانی، حتماً request-id را برای کمک به تشخیص مشکلات وارد کنید.

بهترین شیوه‌ها برای مدیریت خطا

برای ساخت برنامه‌های کاربردی انعطاف‌پذیر، بهترین شیوه‌های زیر را پیاده‌سازی کنید:

  1. بررسی جزئیات خطا: همیشه فیلد details شیء Status را تجزیه و تحلیل کنید، به طور خاص به دنبال GoogleAdsFailure باشید. errorCode ، message و location دقیق آن در GoogleAdsError کاربردی‌ترین اطلاعات را برای اشکال‌زدایی و بازخورد کاربر ارائه می‌دهند.

  2. تشخیص خطاهای کلاینت از خطاهای سرور:

    • خطاهای کلاینت: کدهایی مانند INVALID_ARGUMENT ، NOT_FOUND ، PERMISSION_DENIED ، FAILED_PRECONDITION ، UNAUTHENTICATED . این کدها نیاز به تغییراتی در درخواست یا وضعیت/اعتبارنامه‌های برنامه شما دارند. بدون رسیدگی به مشکل، درخواست را دوباره امتحان نکنید.
    • خطاهای سرور: کدهایی مانند UNAVAILABLE ، INTERNAL ، DEADLINE_EXCEEDED ، UNKNOWN . این کدها نشان دهنده یک مشکل موقت در سرویس API هستند.

  3. یک استراتژی تلاش مجدد پیاده‌سازی کنید:

    • چه زمانی دوباره امتحان کنیم: فقط برای خطاهای گذرای سرور مانند UNAVAILABLE ، DEADLINE_EXCEEDED ، INTERNAL ، UNKNOWN و ABORTED دوباره امتحان کنید.
    • عقب‌نشینی نمایی: از یک الگوریتم عقب‌نشینی نمایی برای انتظار برای دوره‌های افزایشی بین تلاش‌های مجدد استفاده کنید. این به جلوگیری از تحت فشار قرار گرفتن یک سرویس از قبل تحت فشار کمک می‌کند. به عنوان مثال، ۱ ثانیه، سپس ۲ ثانیه، سپس ۴ ثانیه صبر کنید و تا حداکثر تعداد تلاش‌های مجدد یا کل زمان انتظار ادامه دهید.
    • لرزش (Jitter): مقدار تصادفی کمی لرزش (Jitter) به تأخیرهای برگشتی اضافه کنید تا از مشکل «گله رعدآسا» که در آن بسیاری از کلاینت‌ها به‌طور همزمان دوباره تلاش می‌کنند، جلوگیری شود.

  4. گزارش کامل: پاسخ کامل خطا، شامل تمام جزئیات، به ویژه شناسه درخواست را گزارش کنید. این اطلاعات برای اشکال‌زدایی و در صورت نیاز، گزارش مشکلات به پشتیبانی گوگل ضروری است.

  5. ارائه بازخورد کاربر: بر اساس کدها و پیام‌های خاص GoogleAdsError ، بازخورد واضح و مفیدی را به کاربران برنامه خود ارائه دهید. برای مثال، به جای اینکه فقط بگویید «خطایی رخ داده است»، می‌توانید بگویید «نام کمپین مورد نیاز است» یا «شناسه گروه تبلیغاتی ارائه شده یافت نشد».

با پیروی از این دستورالعمل‌ها، می‌توانید خطاهایی را که توسط API تبلیغات گوگل برگردانده می‌شوند، به طور مؤثر تشخیص داده و مدیریت کنید و در نتیجه برنامه‌های پایدارتر و کاربرپسندتری داشته باشید.

قبلی
انواع خطا
بعدی
خطاهای رایج