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

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

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

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

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

{
  "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: การตอบกลับข้อผิดพลาดจากคำขอ HTTP v1 API ที่มีโทเค็นการลงทะเบียนที่ไม่ถูกต้อง

{
  "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 type.googleapis.com/google.rpc.BadRequest ซึ่งบ่งบอกถึงข้อผิดพลาดใน request values ตัวอย่างที่ 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 วินาที แล้วรอ 8 วินาที และอื่นๆ) หากส่งข้อความหลายรายการ ให้ลองใช้การสุ่มเวลา ดูข้อมูลเพิ่มเติมได้ที่ การจัดการการลองใหม่หรือตรวจสอบ แดชบอร์ดสถานะของ 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 ไม่ได้เนื่องจากไม่ได้อัปโหลดหรือ SSL Certificate ของ APNs ที่จำเป็นหมดอายุแล้ว ตรวจสอบ ความถูกต้องของใบรับรองการพัฒนาและใบรับรองการผลิต
messaging/mismatched-credential ข้อมูลเข้าสู่ระบบที่ใช้ในการตรวจสอบสิทธิ์ SDK นี้ไม่มีสิทธิ์ ส่งข้อความไปยังอุปกรณ์ที่สอดคล้องกับโทเค็นการลงทะเบียนที่ระบุ ตรวจสอบว่าข้อมูลเข้าสู่ระบบและโทเค็นการลงทะเบียนเป็นของโปรเจ็กต์ Firebase เดียวกัน ดู เพิ่ม Firebase ลงในแอป เพื่อดูเอกสารประกอบเกี่ยวกับวิธีตรวจสอบสิทธิ์ Firebase Admin SDKs
messaging/authentication-error SDK ตรวจสอบสิทธิ์กับเซิร์ฟเวอร์ FCM ไม่ได้ โปรดตรวจสอบว่าคุณ ได้ตรวจสอบสิทธิ์ Firebase Admin SDK ด้วยข้อมูลเข้าสู่ระบบที่มี สิทธิ์ที่เหมาะสมในการส่งข้อความ FCM ดู เพิ่ม Firebase ลงในแอป เพื่อดูเอกสารประกอบเกี่ยวกับวิธีตรวจสอบสิทธิ์ Firebase Admin SDKs
messaging/server-unavailable เซิร์ฟเวอร์ FCM ประมวลผลคำขอไม่ทัน คุณควร ลองส่งคำขอเดิมอีกครั้ง แต่ต้องทำดังนี้
  • ปฏิบัติตามส่วนหัว Retry-After หากรวมอยู่ในการตอบกลับจากFCMเซิร์ฟเวอร์การเชื่อมต่อ
  • ใช้ Exponential Backoff ในกลไกการลองใหม่ ตัวอย่างเช่น หากคุณรอ 1 วินาทีก่อนลองครั้งแรก ให้รออย่างน้อย 2 วินาทีก่อนลองครั้งถัดไป จากนั้นรอ 4 วินาที และเพิ่ม ช่วงเวลาเป็นวินาทีต่อไป หากคุณส่งข้อความหลายรายการ ให้หน่วงเวลาแต่ละข้อความ แยกกันโดยเพิ่มเวลาแบบสุ่มเพื่อหลีกเลี่ยงการออกคำขอใหม่สำหรับข้อความทั้งหมดในเวลาเดียวกัน
ผู้ส่งที่ก่อให้เกิดปัญหาอาจถูกขึ้นบัญชีดำ
messaging/internal-error เซิร์ฟเวอร์ FCM พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณลองส่งคำขอเดิมอีกครั้งได้โดยทำตามข้อกำหนด ที่ระบุไว้ในแถว messaging/server-unavailable ก่อนหน้านี้ หากข้อผิดพลาด ยังคงอยู่ โปรดรายงานปัญหาไปยังช่องทางสนับสนุนรายงานข้อบกพร่องของเรา
messaging/unknown-error ระบบแสดงข้อผิดพลาดที่ไม่รู้จักเกี่ยวกับเซิร์ฟเวอร์ ดูรายละเอียดเพิ่มเติมได้ในการตอบกลับของเซิร์ฟเวอร์แบบดิบใน ข้อความแสดงข้อผิดพลาด หากได้รับข้อผิดพลาดนี้ โปรดรายงาน ข้อความแสดงข้อผิดพลาดแบบเต็มไปยังช่องทางสนับสนุนรายงานข้อบกพร่องของเรา