รหัสข้อผิดพลาดของ 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 ซึ่งคือ 4096 ไบต์สำหรับข้อความส่วนใหญ่ หรือ 2048 ไบต์ในกรณีของข้อความที่ส่งไปยังหัวข้อ ซึ่งรวมถึงทั้งคีย์และค่า คีย์ข้อมูลไม่ถูกต้อง: ตรวจสอบว่าข้อมูลเพย์โหลดไม่มีคีย์ (เช่น จาก หรือ 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 วินาทีและรอเพิ่มขึ้นเรื่อยๆ) หากคุณส่งข้อความหลายรายการ ให้พิจารณาใช้ Jittering ดูข้อมูลเพิ่มเติมได้ที่ ดูการจัดการการลองอีกครั้ง, หรือตรวจสอบ แดชบอร์ดสถานะ FCM เพื่อ ดูว่ามีบริการขัดข้องที่ส่งผลต่อ FCM หรือไม่ ผู้ส่งที่ก่อให้เกิดปัญหาอาจถูกขึ้นบัญชีดำ
INTERNAL (รหัสข้อผิดพลาด HTTP = 500) เกิดข้อผิดพลาดภายในที่ไม่ทราบสาเหตุ	เซิร์ฟเวอร์พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณสามารถลองส่งคำขอเดิมอีกครั้งโดยทำตามคำแนะนำในการจัดการการลองอีกครั้ง หรือตรวจสอบ แดชบอร์ดสถานะ FCM เพื่อดูว่ามีบริการขัดข้องที่ส่งผลต่อ FCM หรือไม่ หากข้อผิดพลาดยังคงอยู่ โปรดติดต่อทีมสนับสนุน Firebase
THIRD_PARTY_AUTH_ERROR (รหัสข้อผิดพลาด HTTP = 401) ใบรับรอง APNs หรือคีย์การตรวจสอบสิทธิ์การแจ้งเตือนแบบพุชบนเว็บไม่ถูกต้องหรือขาดหายไป	ระบบส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ 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 ขีดจำกัดคือ 4096 ไบต์สำหรับข้อความส่วนใหญ่ สำหรับข้อความที่ส่งไปยังหัวข้อ ขีดจำกัดคือ 2048 ไบต์ ขนาดเพย์โหลดทั้งหมดรวมทั้งคีย์และค่า
messaging/invalid-options	มีการระบุออบเจ็กต์ตัวเลือกข้อความไม่ถูกต้อง ข้อความแสดงข้อผิดพลาดควรมี ข้อมูลเพิ่มเติม
messaging/invalid-registration-token	มีการระบุโทเค็นการลงทะเบียนไม่ถูกต้อง ตรวจสอบว่าโทเค็นตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนกับ FCM อย่าตัดหรือเพิ่มอักขระลงในโทเค็น
messaging/registration-token-not-registered	โทเค็นการลงทะเบียนที่ระบุไม่ได้ลงทะเบียนไว้ โทเค็นการลงทะเบียนที่เคยถูกต้อง อาจถูกยกเลิกการลงทะเบียนด้วยเหตุผลต่างๆ ดังนี้: แอปไคลเอ็นต์ยกเลิกการลงทะเบียนจาก FCM ด้วยตัวเอง ระบบยกเลิกการลงทะเบียนแอปไคลเอ็นต์โดยอัตโนมัติ ซึ่งอาจเกิดขึ้นหาก ผู้ใช้ถอนการติดตั้งแอปพลิเคชัน หรือในแพลตฟอร์ม Apple หากบริการแสดงความคิดเห็นของ APNs รายงานว่าโทเค็น APNs ไม่ถูกต้อง โทเค็นการลงทะเบียนหมดอายุ เช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APNs อาจหมดอายุสำหรับอุปกรณ์ Apple แอปไคลเอ็นต์ได้รับการอัปเดต แต่เวอร์ชันใหม่ไม่ได้กำหนดค่าให้ รับข้อความ ในกรณีเหล่านี้ทั้งหมด ให้นำโทเค็นการลงทะเบียนนี้ออกและหยุดใช้โทเค็นนี้เพื่อ ส่งข้อความ
messaging/invalid-package-name	ข้อความส่งถึงโทเค็นการลงทะเบียนที่มีชื่อแพ็กเกจไม่ตรงกับตัวเลือก restrictedPackageName ที่ระบุ
messaging/message-rate-exceeded	อัตราข้อความที่ส่งไปยังเป้าหมายหนึ่งๆ สูงเกินไป ลดจำนวน ข้อความที่ส่งไปยังอุปกรณ์หรือหัวข้อนี้ และอย่าลองส่ง ส่งไปยังเป้าหมายนี้อีกครั้งทันที
messaging/device-message-rate-exceeded	อัตราข้อความที่ส่งไปยังอุปกรณ์หนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์นี้ และอย่าลองส่งไปยังอุปกรณ์นี้อีกครั้งทันที
messaging/topics-message-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 Backoff ในกลไกการลองอีกครั้ง เช่น หากคุณรอ 1 วินาทีก่อนลองอีกครั้งครั้งแรก ให้รออย่างน้อย 2 วินาทีก่อนลองอีกครั้งครั้งถัดไป จากนั้นรอ 4 วินาที และรอเพิ่มขึ้นเรื่อยๆ หากคุณส่งข้อความหลายรายการ ให้หน่วงเวลาแต่ละ ข้อความแยกกันด้วยระยะเวลาแบบสุ่มเพิ่มเติมเพื่อหลีกเลี่ยงการส่งคำขอใหม่สำหรับข้อความทั้งหมดในเวลาเดียวกัน ผู้ส่งที่ก่อให้เกิดปัญหาอาจถูกขึ้นบัญชีดำ
messaging/internal-error	เซิร์ฟเวอร์ FCM พบข้อผิดพลาดขณะพยายามประมวลผล คำขอ คุณสามารถลองส่งคำขอเดิมอีกครั้งโดยทำตามข้อกำหนดที่ระบุไว้ในแถว messaging/server-unavailable ก่อนหน้านี้ หากข้อผิดพลาดยังคงอยู่ โปรดรายงานปัญหาไปยังช่องทางสนับสนุนการรายงานข้อบกพร่อง
messaging/unknown-error	ระบบแสดงผลข้อผิดพลาดของเซิร์ฟเวอร์ที่ไม่ทราบสาเหตุ ดูการตอบกลับของเซิร์ฟเวอร์แบบดิบใน ข้อความแสดงข้อผิดพลาดเพื่อดูรายละเอียดเพิ่มเติม หากได้รับข้อผิดพลาดนี้ โปรดรายงาน ข้อความแสดงข้อผิดพลาดแบบเต็มไปยัง ช่องทางสนับสนุนการรายงานข้อบกพร่อง