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

รหัสข้อผิดพลาด REST สำหรับ HTTP v1 API

การตอบกลับข้อผิดพลาดของ HTTP สำหรับ HTTP v1 API จะมีรหัสข้อผิดพลาด ข้อความแสดงข้อผิดพลาด และสถานะข้อผิดพลาด นอกจากนี้ยังอาจมีอาร์เรย์ details ที่มีรายละเอียดเพิ่มเติมเกี่ยวกับข้อผิดพลาดด้วย

ตัวอย่างการตอบกลับข้อผิดพลาด 2 รายการมีดังนี้

ตัวอย่างที่ 1: การตอบกลับข้อผิดพลาดจากคำขอ API HTTP v1 ที่มีค่าไม่ถูกต้องในข้อความข้อมูล

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "message.data[0].value",
            "description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
          }
        ]
      }
    ]
  }
}

ตัวอย่างที่ 2: การตอบกลับข้อผิดพลาดจากคำขอ API HTTP v1 ที่มีโทเค็นการลงทะเบียนไม่ถูกต้อง

{
  "error": {
    "code": 400,
    "message": "The registration token is not a valid FCM registration token",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "INVALID_ARGUMENT"
      }
    ]
   }
}

โปรดทราบว่าทั้ง 2 ข้อความมีรหัสและสถานะเหมือนกัน แต่อาร์เรย์รายละเอียดมีค่าในประเภทที่แตกต่างกัน ตัวอย่างแรกมีประเภท type.googleapis.com/google.rpc.BadRequest ซึ่งบ่งบอกถึงข้อผิดพลาดในค่าคำขอ ตัวอย่างที่ 2 ที่มีประเภท type.googleapis.com/google.firebase.fcm.v1.FcmError มีข้อผิดพลาดเฉพาะ FCM สำหรับข้อผิดพลาดหลายรายการ อาร์เรย์รายละเอียดจะมีข้อมูลที่คุณต้องใช้ในการแก้ไขข้อบกพร่องและค้นหาวิธีแก้ไข

ตารางต่อไปนี้แสดงรหัสข้อผิดพลาดของ FCM v1 REST API และคำอธิบาย

รหัสข้อผิดพลาด	คำอธิบายและขั้นตอนการแก้ปัญหา
UNSPECIFIED_ERROR ไม่มีข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดนี้	ไม่มี
INVALID_ARGUMENT (รหัสข้อผิดพลาดของ HTTP = 400) พารามิเตอร์คำขอไม่ถูกต้อง ระบบจะแสดงผลส่วนขยายประเภท google.rpc.BadRequest เพื่อระบุช่องที่ไม่ถูกต้อง	สาเหตุที่อาจเป็นไปได้ ได้แก่ การลงทะเบียนไม่ถูกต้อง, ชื่อแพ็กเกจไม่ถูกต้อง, ข้อความมีขนาดใหญ่เกินไป, คีย์ข้อมูลไม่ถูกต้อง, TTL ไม่ถูกต้อง หรือพารามิเตอร์อื่นๆ ไม่ถูกต้อง การลงทะเบียนไม่ถูกต้อง: ตรวจสอบรูปแบบของโทเค็นการลงทะเบียนที่คุณส่งไปยังเซิร์ฟเวอร์ ตรวจสอบว่าตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนกับ FCM อย่าตัดโทเค็นหรือเพิ่มอักขระเพิ่มเติม ชื่อแพ็กเกจไม่ถูกต้อง: ตรวจสอบว่าข้อความส่งไปยังโทเค็นการลงทะเบียนที่มีชื่อแพ็กเกจตรงกับค่าที่ส่งในคำขอ ข้อความมีขนาดใหญ่เกินไป: ตรวจสอบว่าขนาดรวมของข้อมูลเพย์โหลดที่รวมอยู่ในข้อความไม่เกินขีดจำกัดของ FCM ซึ่งก็คือ 4,096 ไบต์สำหรับข้อความส่วนใหญ่ หรือ 2,048 ไบต์ในกรณีที่เป็นข้อความไปยังหัวข้อ ซึ่งรวมทั้งคีย์และค่า คีย์ข้อมูลไม่ถูกต้อง: ตรวจสอบว่าข้อมูลเพย์โหลดไม่มีคีย์ (เช่น from หรือ gcm หรือค่าใดๆ ที่ขึ้นต้นด้วย google) ที่ FCM ใช้ภายใน โปรดทราบว่า FCM ยังใช้บางคำ (เช่น collapse_key) ด้วย แต่อนุญาตให้ใช้ในเพย์โหลด ซึ่งในกรณีนี้ ค่าเพย์โหลดจะถูกลบล้างด้วยค่า FCM TTL ไม่ถูกต้อง: ตรวจสอบว่าค่าที่ใช้ใน ttl เป็นจำนวนเต็มที่แสดงระยะเวลาเป็นวินาทีระหว่าง 0 ถึง 2,419,200 (4 สัปดาห์) พารามิเตอร์ไม่ถูกต้อง: ตรวจสอบว่าพารามิเตอร์ที่ระบุมีชื่อและประเภทที่ถูกต้อง
UNREGISTERED (รหัสข้อผิดพลาดของ HTTP = 404) ยกเลิกการลงทะเบียนอินสแตนซ์แอปจาก FCM แล้ว ซึ่งโดยปกติแล้วหมายความว่าโทเค็นที่ใช้ไม่ถูกต้องอีกต่อไปและต้องใช้โทเค็นใหม่	ข้อผิดพลาดนี้อาจเกิดจากโทเค็นการลงทะเบียนหายไปหรือโทเค็นที่ไม่ได้ลงทะเบียน ไม่มีการลงทะเบียน: หากเป้าหมายของข้อความเป็นค่า token ให้ตรวจสอบว่าคำขอมีโทเค็นการลงทะเบียน ไม่ได้ลงทะเบียน: โทเค็นการลงทะเบียนที่มีอยู่อาจใช้งานไม่ได้ในหลายสถานการณ์ ซึ่งรวมถึง - หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนกับ FCM - หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนโดยอัตโนมัติ ซึ่งอาจเกิดขึ้นได้หากผู้ใช้ถอนการติดตั้งแอปพลิเคชัน เช่น ใน iOS หากบริการแสดงความคิดเห็นของ APNs รายงานว่าโทเค็น APNs ไม่ถูกต้อง - หากโทเค็นการลงทะเบียนหมดอายุ (เช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APNs หมดอายุสำหรับอุปกรณ์ iOS) - หากแอปไคลเอ็นต์ได้รับการอัปเดต แต่เวอร์ชันใหม่ไม่ได้กำหนดค่าให้รับข้อความ ในกรณีเหล่านี้ทั้งหมด ให้นำโทเค็นการลงทะเบียนนี้ออกจากเซิร์ฟเวอร์แอปและหยุดใช้เพื่อส่งข้อความ
SENDER_ID_MISMATCH (รหัสข้อผิดพลาด HTTP = 403) รหัสผู้ส่งที่ตรวจสอบสิทธิ์แล้วแตกต่างจากรหัสผู้ส่งสำหรับโทเค็นการลงทะเบียน	โทเค็นการลงทะเบียนจะเชื่อมโยงกับกลุ่มผู้ส่งบางกลุ่ม เมื่อแอปไคลเอ็นต์ลงทะเบียน FCM แอปต้องระบุผู้ส่งที่ได้รับอนุญาตให้ส่งข้อความ คุณควรใช้รหัสผู้ส่งรหัสใดรหัสหนึ่งเมื่อส่งข้อความไปยังแอปไคลเอ็นต์ หากเปลี่ยนไปใช้ผู้ส่งรายอื่น โทเค็นการลงทะเบียนที่มีอยู่จะใช้งานไม่ได้
QUOTA_EXCEEDED (รหัสข้อผิดพลาด HTTP = 429) เกินขีดจำกัดการส่งสำหรับเป้าหมายข้อความ ระบบจะแสดงผลส่วนขยายประเภท google.rpc.QuotaFailure เพื่อระบุว่าโควต้าใดเกินขีดจำกัด	ข้อผิดพลาดนี้อาจเกิดจากการเกินโควต้าอัตราข้อความ เกินโควต้าอัตราข้อความของอุปกรณ์ หรือเกินโควต้าอัตราข้อความของหัวข้อ อัตราข้อความเกินขีดจำกัด: อัตราการส่งข้อความสูงเกินไป คุณต้องลดอัตราการส่งข้อความโดยรวม ใช้ Exponential Backoff โดยมีความล่าช้าเริ่มต้นอย่างน้อย 1 นาทีเพื่อลองส่งข้อความที่ถูกปฏิเสธอีกครั้ง อัตราข้อความของอุปกรณ์เกินขีดจำกัด: อัตราข้อความที่ส่งไปยังอุปกรณ์หนึ่งๆ สูงเกินไป ดูการจำกัดอัตราคำขอข้อความไปยังอุปกรณ์เครื่องเดียว ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์นี้และใช้ Exponential Backoff เพื่อลองส่งอีกครั้ง อัตราข้อความหัวข้อเกินขีดจำกัด: อัตราข้อความที่ส่งถึงผู้ติดตามหัวข้อหนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งสำหรับหัวข้อนี้ และใช้ Exponential Backoff โดยมีความล่าช้าเริ่มต้นอย่างน้อย 1 นาทีเพื่อลองส่งอีกครั้ง
UNAVAILABLE (รหัสข้อผิดพลาดของ HTTP = 503) เซิร์ฟเวอร์ทำงานหนักเกินไป	เซิร์ฟเวอร์ประมวลผลคำขอไม่ทันเวลา ลองส่งคำขอเดิมอีกครั้ง แต่คุณต้องทำดังนี้ - ปฏิบัติตามส่วนหัว Retry-After หากมีอยู่ในคำตอบจากเซิร์ฟเวอร์การเชื่อมต่อ FCM - ใช้ Exponential Backoff ในกลไกการลองใหม่ (เช่น หากคุณรอ 1 วินาทีก่อนลองใหม่ครั้งแรก ให้รออย่างน้อย 2 วินาทีก่อนลองใหม่ครั้งถัดไป จากนั้นรอ 4 วินาที และเพิ่มขึ้นเรื่อยๆ) หากคุณส่งข้อความหลายรายการ ให้พิจารณาใช้การกระวนกระวายใจ ดูข้อมูลเพิ่มเติมได้ที่การจัดการการลองใหม่หรือตรวจสอบ แดชบอร์ดสถานะ FCM เพื่อดูว่ามีบริการขัดข้องที่กำลังเกิดขึ้นซึ่งส่งผลต่อ FCM หรือไม่ ผู้ส่งที่ทำให้เกิดปัญหาอาจถูกเพิ่มลงในรายการที่ปฏิเสธ
INTERNAL (รหัสข้อผิดพลาดของ HTTP = 500) เกิดข้อผิดพลาดภายในที่ไม่ทราบสาเหตุ	เซิร์ฟเวอร์พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณสามารถลองส่งคำขอเดิมอีกครั้งตามคำแนะนำในการจัดการการลองใหม่ หรือตรวจสอบ แดชบอร์ดสถานะ FCM เพื่อดูว่ามีการหยุดชะงักของบริการที่กำลังเกิดขึ้นซึ่งส่งผลต่อ FCM หรือไม่ หากข้อผิดพลาดยังคงอยู่ โปรดติดต่อทีมสนับสนุนของ Firebase
THIRD_PARTY_AUTH_ERROR (รหัสข้อผิดพลาด HTTP = 401) ใบรับรอง APNs หรือคีย์การตรวจสอบสิทธิ์ข้อความ Push บนเว็บไม่ถูกต้องหรือไม่มี	ส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ iOS หรือการลงทะเบียนพุชบนเว็บไม่ได้ ตรวจสอบความถูกต้องของข้อมูลเข้าสู่ระบบสำหรับการพัฒนาและการใช้งานจริง

รหัสข้อผิดพลาดของ Admin SDK

ตารางต่อไปนี้แสดงรหัสข้อผิดพลาดของ Firebase Admin FCM API และคำอธิบาย รวมถึงขั้นตอนการแก้ปัญหาที่แนะนำ

รหัสข้อผิดพลาด	คำอธิบายและขั้นตอนการแก้ปัญหา
messaging/invalid-argument	มีการระบุอาร์กิวเมนต์ที่ไม่ถูกต้องให้กับเมธอด FCM ข้อความแสดงข้อผิดพลาดควรมีข้อมูลเพิ่มเติม
messaging/invalid-recipient	ผู้รับข้อความที่ต้องการไม่ถูกต้อง ข้อความแสดงข้อผิดพลาดควรมีข้อมูลเพิ่มเติม
messaging/invalid-payload	ออบเจ็กต์เพย์โหลดข้อความที่ระบุไม่ถูกต้อง ข้อความแสดงข้อผิดพลาดควรมีข้อมูลเพิ่มเติม
messaging/invalid-data-payload-key	เพย์โหลดข้อความข้อมูลมีคีย์ที่ไม่ถูกต้อง ดูเอกสารอ้างอิงสำหรับ DataMessagePayload เกี่ยวกับคีย์ที่ถูกจำกัด
messaging/payload-size-limit-exceeded	เพย์โหลดข้อความที่ระบุมีขนาดเกินขีดจำกัด FCM ขีดจำกัดคือ 4,096 ไบต์สำหรับข้อความส่วนใหญ่ สำหรับข้อความที่ส่งไปยังหัวข้อ ขีดจำกัดคือ 2,048 ไบต์ ขนาดเพย์โหลดทั้งหมดจะรวมทั้งคีย์และค่า
messaging/invalid-options	มีการระบุออบเจ็กต์ตัวเลือกข้อความที่ไม่ถูกต้อง ข้อความแสดงข้อผิดพลาดควรมีข้อมูลเพิ่มเติม
messaging/invalid-registration-token	โทเค็นการลงทะเบียนที่ระบุไม่ถูกต้อง ตรวจสอบว่าตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนกับ FCM อย่าตัดหรือเพิ่มอักขระเพิ่มเติม
messaging/registration-token-not-registered	โทเค็นการลงทะเบียนที่ระบุไม่ได้ลงทะเบียนไว้ โทเค็นการลงทะเบียนที่ถูกต้องก่อนหน้านี้อาจยกเลิกการลงทะเบียนได้ด้วยเหตุผลหลายประการ เช่น แอปไคลเอ็นต์ยกเลิกการลงทะเบียนตัวเองจาก FCM ระบบยกเลิกการลงทะเบียนแอปไคลเอ็นต์โดยอัตโนมัติ ซึ่งอาจเกิดขึ้นหากผู้ใช้ถอนการติดตั้งแอปพลิเคชัน หรือในแพลตฟอร์ม Apple หากบริการความคิดเห็นของ APN รายงานว่าโทเค็น APN ไม่ถูกต้อง โทเค็นการลงทะเบียนหมดอายุแล้ว ตัวอย่างเช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APN อาจหมดอายุสำหรับอุปกรณ์ Apple แอปไคลเอ็นต์ได้รับการอัปเดตแล้ว แต่เวอร์ชันใหม่ไม่ได้กำหนดค่าให้รับข้อความ ในกรณีเหล่านี้ทั้งหมด ให้นำโทเค็นการลงทะเบียนนี้ออกและหยุดใช้เพื่อส่งข้อความ
messaging/invalid-package-name	ข้อความส่งไปยังโทเค็นการลงทะเบียนซึ่งมีชื่อแพ็กเกจไม่ตรงกับตัวเลือก restrictedPackageName ที่ระบุ
messaging/message-rate-exceeded	อัตราของข้อความที่ส่งไปยังเป้าหมายหนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์หรือหัวข้อนี้ และอย่าลองส่งไปยังเป้าหมายนี้อีกครั้งในทันที
messaging/device-message-rate-exceeded	อัตราของข้อความที่ส่งไปยังอุปกรณ์หนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์นี้และอย่าลองส่งไปยังอุปกรณ์นี้อีกครั้งในทันที
messaging/topics-message-rate-exceeded	อัตราของข้อความที่ส่งถึงผู้ติดตามในหัวข้อหนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งสำหรับหัวข้อนั้น และอย่าลองส่งไปยังหัวข้อนั้นอีกครั้งในทันที
messaging/topics-subscription-rate-exceeded	อัตราคำขอการจัดการการสมัครใช้บริการในหัวข้อหนึ่งๆ สูงเกินไป ลดจำนวนคำขอที่ส่งสำหรับหัวข้อนั้น และอย่าลองส่งคำขออีกครั้งทันที
messaging/too-many-topics	โทเค็นการลงทะเบียนสมัครรับหัวข้อถึงจำนวนสูงสุดแล้ว และไม่สามารถสมัครรับหัวข้อได้อีก
messaging/invalid-apns-credentials	ส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ Apple ไม่ได้เนื่องจากไม่ได้อัปโหลดใบรับรอง APNs SSL ที่จำเป็นหรือใบรับรองหมดอายุแล้ว ตรวจสอบความถูกต้องของใบรับรองการพัฒนาและการใช้งานจริง
messaging/mismatched-credential	ข้อมูลเข้าสู่ระบบที่ใช้ในการตรวจสอบสิทธิ์ SDK นี้ไม่มีสิทธิ์ส่งข้อความไปยังอุปกรณ์ที่สอดคล้องกับโทเค็นการลงทะเบียนที่ระบุ ตรวจสอบว่าทั้งข้อมูลเข้าสู่ระบบและโทเค็นการลงทะเบียนเป็นของโปรเจ็กต์ Firebase เดียวกัน ดูเอกสารประกอบเกี่ยวกับวิธีตรวจสอบสิทธิ์ Firebase Admin SDKs ได้ที่หัวข้อเพิ่ม Firebase ลงในแอป
messaging/authentication-error	SDK ตรวจสอบสิทธิ์กับเซิร์ฟเวอร์ FCM ไม่ได้ ตรวจสอบว่าคุณตรวจสอบสิทธิ์ Firebase Admin SDK ด้วยข้อมูลเข้าสู่ระบบที่มีสิทธิ์ที่เหมาะสมในการส่งข้อความ FCM ดูเอกสารประกอบเกี่ยวกับวิธีตรวจสอบสิทธิ์ Firebase Admin SDKs ได้ที่หัวข้อเพิ่ม Firebase ลงในแอป
messaging/server-unavailable	เซิร์ฟเวอร์ FCM ประมวลผลคำขอไม่ทันเวลา คุณควรลองส่งคำขอเดิมอีกครั้ง แต่ต้องดำเนินการดังนี้ ใช้ส่วนหัว Retry-After หากมีอยู่ในคำตอบจากเซิร์ฟเวอร์การเชื่อมต่อ FCM ใช้ Exponential Back-off ในกลไกการลองใหม่ ตัวอย่างเช่น หากคุณรอ 1 วินาทีก่อนที่จะลองใหม่ครั้งแรก ให้รออย่างน้อย 2 วินาทีก่อนที่จะลองใหม่ครั้งถัดไป จากนั้นรอ 4 วินาที และเพิ่มช่วงเวลาเป็นวินาทีไปเรื่อยๆ หากคุณส่งข้อความหลายรายการ ให้หน่วงเวลาแต่ละรายการอย่างอิสระด้วยจำนวนสุ่มเพิ่มเติมเพื่อหลีกเลี่ยงการส่งคำขอใหม่สำหรับข้อความทั้งหมดพร้อมกัน ผู้ส่งที่ทำให้เกิดปัญหาอาจเสี่ยงต่อการถูกเพิ่มลงในรายการที่บล็อก
messaging/internal-error	เซิร์ฟเวอร์ FCM พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณสามารถลองส่งคำขอเดิมอีกครั้งตามข้อกำหนดที่ระบุไว้ในแถว messaging/server-unavailable ก่อนหน้า หากข้อผิดพลาดยังคงอยู่ โปรดรายงานปัญหาไปยังช่องทางการสนับสนุนรายงานข้อบกพร่องของเรา
messaging/unknown-error	เซิร์ฟเวอร์แสดงข้อผิดพลาดที่ไม่รู้จัก ดูรายละเอียดเพิ่มเติมเกี่ยวกับการตอบกลับของเซิร์ฟเวอร์แบบข้อมูลดิบในข้อความแสดงข้อผิดพลาด หากได้รับข้อผิดพลาดนี้ โปรดรายงานข้อความแสดงข้อผิดพลาดทั้งหมดไปยังช่องทางการสนับสนุนรายงานข้อบกพร่องของเรา