ทำความเข้าใจข้อผิดพลาดของ API

คู่มือนี้อธิบายวิธีที่ Google Ads API จัดการและสื่อสารข้อผิดพลาด การทำความเข้าใจโครงสร้างและความหมายของข้อผิดพลาดของ API เป็นสิ่งสำคัญอย่างยิ่งในการสร้าง แอปพลิเคชันที่มีประสิทธิภาพซึ่งสามารถจัดการปัญหาได้อย่างราบรื่น ตั้งแต่ข้อมูลที่ไม่ถูกต้องไปจนถึง บริการที่ไม่พร้อมใช้งานชั่วคราว

Google Ads API ใช้รูปแบบข้อผิดพลาดของ Google API มาตรฐาน ซึ่งอิงตามรหัสสถานะ gRPC การตอบกลับ API แต่ละรายการที่ทำให้เกิดข้อผิดพลาดจะมีออบเจ็กต์ Status ที่มีข้อมูลต่อไปนี้

• รหัสข้อผิดพลาดที่เป็นตัวเลข
• ข้อความแสดงข้อผิดพลาด
• รายละเอียดข้อผิดพลาดเพิ่มเติม (ไม่บังคับ)

รหัสข้อผิดพลาด Canonical

Google Ads API ใช้ชุดรหัสข้อผิดพลาด Canonical ที่กำหนดโดย gRPC และ HTTP รหัสเหล่านี้ ระบุประเภทข้อผิดพลาดในระดับสูง คุณควรตรวจสอบรหัสตัวเลขนี้ก่อนเสมอเพื่อทำความเข้าใจลักษณะพื้นฐานของปัญหา

ตารางต่อไปนี้สรุปรหัสที่พบบ่อยที่สุดซึ่งคุณอาจพบเมื่อ ใช้ Google Ads API

โค้ด gRPC	รหัส HTTP	ชื่อ Enum	คำอธิบาย	คำแนะนำ
0	200	OK	ไม่มีข้อผิดพลาด แสดงว่าสำเร็จ	ไม่มี
1	499	CANCELLED	การดำเนินการถูกยกเลิก โดยปกติแล้วจะเป็นไคลเอ็นต์	โดยปกติแล้วหมายความว่าไคลเอ็นต์หยุดรอ ตรวจสอบการหมดเวลาฝั่งไคลเอ็นต์
2	500	UNKNOWN	เกิดข้อผิดพลาดที่ไม่รู้จัก ข้อความแสดงข้อผิดพลาดหรือรายละเอียดอาจมีข้อมูลเพิ่มเติม	ถือว่าเป็นข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์ มักลองอีกครั้งได้โดยใช้การหยุดชั่วคราว
3	400	INVALID_ARGUMENT	ไคลเอ็นต์ระบุอาร์กิวเมนต์ไม่ถูกต้อง ปัญหานี้บ่งบอกถึงปัญหาที่ทำให้ API ประมวลผลคำขอไม่ได้ เช่น ชื่อทรัพยากรที่จัดรูปแบบไม่ถูกต้องหรือค่าที่ไม่ถูกต้อง	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบพารามิเตอร์คำขอและดูว่าเป็นไปตามข้อกำหนดของ API โดยปกติแล้ว รายละเอียดข้อผิดพลาดจะให้ข้อมูลเกี่ยวกับอาร์กิวเมนต์ที่ไม่ถูกต้องและวิธีแก้ไขคำขอ อย่าลองอีกครั้งโดยไม่แก้ไขคำขอ
4	504	DEADLINE_EXCEEDED	กำหนดเวลาหมดอายุก่อนที่การดำเนินการจะเสร็จสมบูรณ์	ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์: มักเกิดขึ้นชั่วคราว ลองอีกครั้งโดยใช้ Exponential Backoff
5	404	NOT_FOUND	ไม่พบเอนทิตีที่ขอ เช่น แคมเปญหรือกลุ่มโฆษณา	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบว่าทรัพยากรที่คุณพยายามเข้าถึงมีอยู่จริงและมีรหัส อย่าลองอีกครั้งโดยไม่แก้ไข
6	409	ALREADY_EXISTS	มีเอนทิตีที่ไคลเอ็นต์พยายามสร้างอยู่แล้ว	ข้อผิดพลาดของไคลเอ็นต์: หลีกเลี่ยงการสร้างทรัพยากรที่ซ้ำกัน ตรวจสอบว่ามีทรัพยากรอยู่หรือไม่ก่อนที่จะพยายามสร้าง
7	403	PERMISSION_DENIED	ผู้โทรไม่มีสิทธิ์ดำเนินการที่ระบุ	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบการตรวจสอบสิทธิ์ การให้สิทธิ์ และบทบาทของผู้ใช้สำหรับบัญชี Google Ads อย่าลองอีกครั้งโดยไม่แก้ไขสิทธิ์
8	429	RESOURCE_EXHAUSTED	อาจเป็นเพราะทรัพยากรหมด (เช่น คุณใช้เกินโควต้า) หรือระบบทำงานหนักเกินไป	ข้อผิดพลาดของไคลเอ็นต์/เซิร์ฟเวอร์: โดยปกติจะต้องรอ ใช้ Exponential Backoff และอาจลดอัตราคำขอ ดูขีดจำกัดและโควต้า API
9	400	FAILED_PRECONDITION	ระบบปฏิเสธการดำเนินการเนื่องจากระบบไม่อยู่ในสถานะที่จำเป็นสำหรับการดำเนินการ เช่น ไม่มีข้อมูลในช่องที่ต้องกรอก	ข้อผิดพลาดของไคลเอ็นต์: คำขอถูกต้อง แต่สถานะไม่ถูกต้อง ตรวจสอบรายละเอียดข้อผิดพลาดเพื่อทำความเข้าใจสาเหตุที่ทำให้ไม่เป็นไปตามเงื่อนไขเบื้องต้น อย่าลองอีกครั้งโดยไม่แก้ไขรัฐ
10	409	ABORTED	การดำเนินการถูกยกเลิก ซึ่งมักเกิดจากปัญหาการทำงานพร้อมกัน เช่น ความขัดแย้งของธุรกรรม	ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์: มักจะลองใหม่ได้อย่างปลอดภัยโดยมีการหยุดชั่วคราวสั้นๆ
11	400	OUT_OF_RANGE	การดำเนินการพยายามดำเนินการนอกช่วงที่ถูกต้อง	ข้อผิดพลาดของไคลเอ็นต์: แก้ไขช่วงหรือดัชนี
12	501	UNIMPLEMENTED	API ไม่ได้ใช้หรือรองรับการดำเนินการนี้	ข้อผิดพลาดของไคลเอ็นต์: ตรวจสอบเวอร์ชัน API และฟีเจอร์ที่พร้อมใช้งาน ไม่ต้องลองใหม่
13	500	INTERNAL	เกิดข้อผิดพลาดภายใน นี่คือการแก้ปัญหาทั่วไปสำหรับปัญหาฝั่งเซิร์ฟเวอร์	ข้อผิดพลาดของเซิร์ฟเวอร์: โดยทั่วไปจะลองอีกครั้งได้โดยใช้ Exponential Backoff หากยังพบปัญหาอยู่ โปรดรายงานปัญหา
14	503	UNAVAILABLE	ไม่พร้อมให้บริการนี้ในขณะนี้ ซึ่งมักเป็นเพียงชั่วคราว	ข้อผิดพลาดของเซิร์ฟเวอร์: ขอแนะนำให้ลองอีกครั้งโดยใช้ Exponential Backoff
15	500	DATA_LOSS	ข้อมูลสูญหายโดยกู้คืนไม่ได้หรือข้อมูลเสียหาย	ข้อผิดพลาดเกี่ยวกับเซิร์ฟเวอร์: นานๆ ครั้ง บ่งบอกถึงปัญหาร้ายแรง ไม่ต้องลองใหม่ หากยังพบปัญหาอยู่ โปรดรายงานปัญหา
16	401	UNAUTHENTICATED	คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้อง	ข้อผิดพลาดของไคลเอ็นต์: ยืนยันโทเค็นการตรวจสอบสิทธิ์และข้อมูลเข้าสู่ระบบ อย่าลองอีกครั้งโดยไม่แก้ไขการตรวจสอบสิทธิ์

ดูรายละเอียดเพิ่มเติมเกี่ยวกับรหัสเหล่านี้ได้ที่คู่มือการออกแบบ API - รหัสข้อผิดพลาด

ทำความเข้าใจรายละเอียดข้อผิดพลาด

นอกเหนือจากโค้ดระดับบนสุดแล้ว Google Ads API ยังให้ข้อมูลข้อผิดพลาดที่เฉพาะเจาะจงมากขึ้นภายในฟิลด์ details ของออบเจ็กต์ Status ฟิลด์นี้มักจะมี GoogleAdsFailure โปรโต ซึ่งรวมถึงรายการของออบเจ็กต์ GoogleAdsError แต่ละรายการ

ออบเจ็กต์ GoogleAdsFailure แต่ละรายการจะมีข้อมูลต่อไปนี้

• errors: รายการออบเจ็กต์ GoogleAdsError แต่ละรายการจะแสดงรายละเอียดข้อผิดพลาดที่เฉพาะเจาะจงที่เกิดขึ้น
• request_id: รหัสที่ไม่ซ้ำกันสำหรับคำขอ ซึ่งมีประโยชน์สำหรับการแก้ไขข้อบกพร่องและวัตถุประสงค์ในการสนับสนุน

ออบเจ็กต์ GoogleAdsError แต่ละรายการมีข้อมูลต่อไปนี้

• errorCode: รหัสข้อผิดพลาดที่ละเอียดยิ่งขึ้น เฉพาะ Google Ads API เช่น AuthenticationError.NOT_ADS_USER
• message: คำอธิบายข้อผิดพลาดที่เฉพาะเจาะจงซึ่งมนุษย์อ่านได้
• trigger: ค่าที่ทำให้เกิดข้อผิดพลาด หากมี
• location: อธิบายตำแหน่งในคำขอ ที่เกิดข้อผิดพลาด รวมถึงเส้นทางของฟิลด์
• details: รายละเอียดข้อผิดพลาดเพิ่มเติม เช่น สาเหตุของข้อผิดพลาดที่ไม่ได้เผยแพร่

ตัวอย่างรายละเอียดข้อผิดพลาด

เมื่อได้รับข้อผิดพลาด Client Library จะ อนุญาตให้คุณเข้าถึงรายละเอียดเหล่านี้ เช่น INVALID_ARGUMENT (รหัส 3) อาจมีรายละเอียด 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 แบบสตรีม

เมื่อการเรียก API ล้มเหลวโดยไม่ได้ใช้การล้มเหลวบางส่วน รวมถึงการเรียกสตรีมมิง ออบเจ็กต์ GoogleAdsFailure จะแสดงเป็นส่วนหนึ่งของข้อมูลเมตาต่อท้ายในส่วนหัวของการตอบกลับ gRPC หากคุณใช้ REST สำหรับการโทรมาตรฐาน ระบบจะส่ง GoogleAdsFailure ในการตอบกลับ HTTP โดยปกติแล้ว Client libraries จะ แสดงข้อผิดพลาดนี้เป็นข้อยกเว้นที่มีแอตทริบิวต์ GoogleAdsFailure

ไม่สำเร็จบางส่วน

หากใช้ partial failure ระบบจะแสดงข้อผิดพลาดสําหรับการดําเนินการที่ล้มเหลวในฟิลด์ 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
   • Exponential Backoff: ใช้อัลกอริทึม Exponential Backoff เพื่อรอ ระยะเวลาที่เพิ่มขึ้นระหว่างการลองใหม่ ซึ่งจะช่วยไม่ให้บริการที่ทำงานหนักอยู่แล้วต้องรับภาระมากเกินไป เช่น รอ 1 วินาที แล้วรอ 2 วินาที จากนั้นรอ 4 วินาที รอต่อไปจนกว่าจะถึงจำนวนการลองใหม่สูงสุดหรือเวลารอทั้งหมด
   • Jitter: เพิ่ม "Jitter" แบบสุ่มเล็กน้อยลงในระยะเวลาหน่วงของการหยุดชั่วคราวเพื่อ ป้องกันปัญหา "ฝูงชนที่โกลาหล" ซึ่งไคลเอ็นต์จำนวนมากจะลองใหม่ พร้อมกัน

4. บันทึกอย่างละเอียด: บันทึกการตอบกลับข้อผิดพลาดทั้งหมด รวมถึงรายละเอียดทั้งหมด โดยเฉพาะรหัสคำขอ ข้อมูลนี้มีความสำคัญต่อการแก้ไขข้อบกพร่องและ การรายงานปัญหาไปยังทีมสนับสนุนของ Google หากจำเป็น

5. ให้ความคิดเห็นของผู้ใช้: ให้ความคิดเห็นที่ชัดเจนและเป็นประโยชน์แก่ผู้ใช้แอปพลิเคชันของคุณโดยอิงตามรหัสและข้อความที่เฉพาะเจาะจง GoogleAdsError เช่น แทนที่จะพูดว่า "เกิดข้อผิดพลาด" คุณสามารถพูดว่า "ต้องระบุชื่อแคมเปญ" หรือ "ไม่พบรหัสกลุ่มโฆษณาที่ระบุ"

การปฏิบัติตามหลักเกณฑ์เหล่านี้จะช่วยให้คุณวินิจฉัยและจัดการข้อผิดพลาดที่ Google Ads API แสดงผลได้อย่างมีประสิทธิภาพ ซึ่งจะช่วยให้แอปพลิเคชันมีความเสถียรและใช้งานง่ายมากขึ้น