Mã lỗi REST cho API HTTP phiên bản 1
Phản hồi lỗi HTTP cho API HTTP phiên bản 1 chứa mã lỗi, thông báo lỗi và trạng thái lỗi. Các phản hồi này cũng có thể chứa một mảng details có thêm thông tin chi tiết về lỗi.
Sau đây là hai phản hồi lỗi mẫu:
Ví dụ 1: Phản hồi lỗi từ một yêu cầu API HTTP phiên bản 1 có giá trị không hợp lệ trong thông báo dữ liệu
{
"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"
}
]
}
]
}
}
Ví dụ 2: Phản hồi lỗi từ một yêu cầu API HTTP phiên bản 1 có mã thông báo đăng ký không hợp lệ
{
"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"
}
]
}
}
Xin lưu ý rằng cả hai thông báo đều có cùng mã và trạng thái, nhưng mảng chi tiết chứa các giá trị thuộc nhiều loại. Ví dụ đầu tiên có loại type.googleapis.com/google.rpc.BadRequest cho biết lỗi trong các giá trị yêu cầu. Ví dụ thứ hai có loại type.googleapis.com/google.firebase.fcm.v1.FcmError có lỗi dành riêng cho FCM.
Đối với nhiều lỗi, mảng chi tiết chứa thông tin bạn cần để gỡ lỗi và tìm giải pháp.
Bảng sau đây liệt kê các mã lỗi của FCM v1 API REST và nội dung mô tả tương ứng.
| Mã lỗi | Nội dung mô tả và các bước giải quyết |
|---|---|
UNSPECIFIED_ERROR Không có thêm thông tin về lỗi này. |
Không có. |
INVALID_ARGUMENT (Mã lỗi HTTP = 400) Tham số yêu cầu không hợp lệ. Hệ thống sẽ trả về một tiện ích thuộc loại google.rpc.BadRequest để chỉ định trường không hợp lệ. |
Các nguyên nhân có thể bao gồm thông tin đăng ký không hợp lệ, tên gói không hợp lệ, thông báo quá lớn, khoá dữ liệu không hợp lệ, TTL không hợp lệ hoặc các thông số không hợp lệ khác. Đăng ký không hợp lệ: Kiểm tra định dạng của mã thông báo đăng ký mà bạn chuyển đến máy chủ. Đảm bảo mã thông báo này khớp với mã thông báo đăng ký mà ứng dụng khách nhận được khi đăng ký với FCM. Đừng cắt bớt mã thông báo hoặc thêm ký tự. Tên gói không hợp lệ: Đảm bảo thông báo được gửi đến mã thông báo đăng ký có tên gói khớp với giá trị được truyền trong yêu cầu. Thông báo quá lớn: Kiểm tra để đảm bảo tổng kích thước của dữ liệu tải trọng có trong thông báo không vượt quá giới hạn của FCM: 4096 byte đối với hầu hết thông báo hoặc 2048 byte đối với thông báo cho chủ đề. Điều này bao gồm cả khoá và giá trị. Khoá dữ liệu không hợp lệ: Kiểm tra để đảm bảo dữ liệu tải trọng không chứa khoá (chẳng hạn như từ, gcm hoặc bất kỳ giá trị nào có tiền tố google) mà FCM sử dụng nội bộ. Xin lưu ý rằng một số từ (chẳng hạn như collapse_key) cũng được FCM sử dụng nhưng được cho phép trong tải trọng. Trong trường hợp này, giá trị tải trọng sẽ bị giá trị FCM ghi đè. TTL không hợp lệ: Kiểm tra để đảm bảo giá trị được dùng trong ttl là một số nguyên thể hiện thời lượng tính bằng giây trong khoảng từ 0 đến 2.419.200 (4 tuần). Tham số không hợp lệ: Kiểm tra để đảm bảo các tham số được cung cấp có tên và loại chính xác. |
UNREGISTERED (Mã lỗi HTTP = 404) Phiên bản ứng dụng đã bị huỷ đăng ký khỏi FCM. Điều này thường có nghĩa là mã thông báo được sử dụng không còn hợp lệ và bạn phải sử dụng mã thông báo mới. |
Lỗi này có thể là do thiếu mã thông báo đăng ký hoặc mã thông báo chưa đăng ký. Thiếu thông tin đăng ký: Nếu mục tiêu của thông báo là một giá trị token, hãy kiểm tra để đảm bảo yêu cầu có chứa mã thông báo đăng ký.Not registered: Mã thông báo đăng ký hiện có có thể không còn hợp lệ trong một số trường hợp, bao gồm: – Nếu ứng dụng khách huỷ đăng ký với FCM. – Nếu ứng dụng khách tự động huỷ đăng ký, điều này có thể xảy ra nếu người dùng gỡ cài đặt ứng dụng. Ví dụ: trên iOS, nếu Dịch vụ phản hồi APN báo cáo mã thông báo APN là không hợp lệ. – Nếu mã thông báo đăng ký hết hạn (ví dụ: Google có thể quyết định làm mới mã thông báo đăng ký hoặc mã thông báo APN đã hết hạn đối với thiết bị iOS). – Nếu ứng dụng khách được cập nhật nhưng phiên bản mới không được định cấu hình để nhận thông báo. Trong tất cả các trường hợp này, hãy xoá mã thông báo đăng ký này khỏi máy chủ ứng dụng và ngừng sử dụng mã thông báo này để gửi thông báo. |
SENDER_ID_MISMATCH (Mã lỗi HTTP = 403) Mã người gửi đã xác thực khác với mã người gửi cho mã thông báo đăng ký. |
Mã đăng ký được liên kết với một nhóm người gửi nhất định. Khi đăng ký FCM, ứng dụng khách phải chỉ định người gửi nào được phép gửi thông báo. Bạn nên sử dụng một trong các mã nhận dạng người gửi đó khi gửi thông báo đến ứng dụng khách. Nếu bạn chuyển sang một người gửi khác, thì mã thông báo đăng ký hiện có sẽ không hoạt động. |
QUOTA_EXCEEDED (Mã lỗi HTTP = 429) Đã vượt quá hạn mức gửi cho mục tiêu của thông báo. Một tiện ích thuộc loại google.rpc.QuotaFailure được trả về để chỉ định hạn mức đã vượt quá. |
Lỗi này có thể là do vượt quá hạn mức về tần suất gửi thông báo, vượt quá hạn mức về tần suất gửi thông báo đến thiết bị hoặc vượt quá hạn mức về tần suất gửi thông báo theo chủ đề. Vượt quá tốc độ gửi tin nhắn: Tốc độ gửi tin nhắn quá cao. Bạn phải giảm tỷ lệ gửi thư tổng thể. Sử dụng thuật toán thời gian đợi luỹ thừa với độ trễ ban đầu tối thiểu là 1 phút để thử gửi lại các thông báo bị từ chối. Vượt quá tỷ lệ tin nhắn của thiết bị: Tỷ lệ tin nhắn đến một thiết bị cụ thể quá cao. Xem giới hạn tốc độ gửi tin nhắn đến một thiết bị. Giảm số lượng thông báo được gửi đến thiết bị này và sử dụng thuật toán thời gian đợi luỹ thừa để thử gửi lại. Vượt quá tỷ lệ tin nhắn theo chủ đề: Tỷ lệ tin nhắn gửi đến người đăng ký một chủ đề cụ thể quá cao. Hãy giảm số lượng tin nhắn được gửi cho chủ đề này và sử dụng thuật toán thời gian đợi luỹ thừa với độ trễ ban đầu tối thiểu là 1 phút để thử gửi lại. |
UNAVAILABLE (Mã lỗi HTTP = 503) Máy chủ bị quá tải. |
Máy chủ không thể xử lý yêu cầu kịp thời. Thử lại cùng một yêu cầu, nhưng bạn phải: – Tuân thủ tiêu đề Retry-After nếu tiêu đề này có trong phản hồi từ Máy chủ kết nối FCM. – Triển khai thuật toán đợi luỹ tiến trong cơ chế thử lại. (ví dụ: nếu bạn đợi một giây trước lần thử lại đầu tiên, hãy đợi ít nhất hai giây trước lần thử lại tiếp theo, sau đó là 4 giây, v.v.). Nếu bạn đang gửi nhiều thông báo, hãy cân nhắc áp dụng độ trễ. Để biết thêm thông tin, hãy xem phần Xử lý việc thử lại, hoặc kiểm tra Trang tổng quan về trạng thái FCM để xác định xem có dịch vụ nào đang bị gián đoạn và ảnh hưởng đến FCM hay không. Những người gửi gây ra vấn đề có nguy cơ bị đưa vào danh sách từ chối. |
INTERNAL (Mã lỗi HTTP = 500) Đã xảy ra lỗi nội bộ không xác định. |
Máy chủ đã gặp lỗi khi cố gắng xử lý yêu cầu. Bạn có thể thử lại cùng một yêu cầu theo các đề xuất trong phần Xử lý việc thử lại hoặc kiểm tra Trang tổng quan về trạng thái FCM. để xác định xem có dịch vụ nào đang bị gián đoạn và ảnh hưởng đến FCM hay không. Nếu lỗi vẫn tiếp diễn, vui lòng liên hệ với nhóm hỗ trợ Firebase. |
THIRD_PARTY_AUTH_ERROR (Mã lỗi HTTP = 401) Chứng chỉ APN hoặc khoá xác thực thông báo đẩy trên web không hợp lệ hoặc bị thiếu. |
Không gửi được thông báo nhắm đến một thiết bị iOS hoặc một lượt đăng ký thông báo đẩy trên web. Kiểm tra tính hợp lệ của thông tin xác thực phát triển và sản xuất. |
Mã lỗi SDK dành cho quản trị viên
Bảng sau đây liệt kê các mã lỗi của Firebase Admin FCM API và nội dung mô tả, bao gồm cả các bước giải quyết được đề xuất.
| Mã lỗi | Nội dung mô tả và các bước giải quyết |
|---|---|
messaging/invalid-argument |
Một đối số không hợp lệ đã được cung cấp cho phương thức FCM. Thông báo lỗi sẽ chứa thông tin bổ sung. |
messaging/invalid-recipient |
Người nhận thư dự kiến không hợp lệ. Thông báo lỗi phải chứa thông tin bổ sung. |
messaging/invalid-payload |
Đối tượng tải trọng thông báo không hợp lệ đã được cung cấp. Thông báo lỗi phải chứa thông tin bổ sung. |
messaging/invalid-data-payload-key |
Trọng tải thông báo dữ liệu chứa khoá không hợp lệ. Hãy xem tài liệu tham khảo về
DataMessagePayload để biết các khoá bị hạn chế.
|
messaging/payload-size-limit-exceeded |
Tải trọng thông báo được cung cấp vượt quá giới hạn kích thước FCM. Giới hạn là 4096 byte cho hầu hết các thông báo. Đối với thông báo được gửi đến chủ đề, giới hạn là 2048 byte. Tổng kích thước gói dữ liệu bao gồm cả khoá và giá trị. |
messaging/invalid-options |
Đối tượng tuỳ chọn thông báo không hợp lệ đã được cung cấp. Thông báo lỗi phải chứa thông tin bổ sung. |
messaging/invalid-registration-token |
Mã thông báo đăng ký bạn cung cấp không hợp lệ. Hãy đảm bảo mã thông báo này khớp với mã thông báo đăng ký mà ứng dụng khách nhận được khi đăng ký với FCM. Đừng cắt bớt hoặc thêm ký tự vào mã này. |
messaging/registration-token-not-registered |
Mã thông báo đăng ký được cung cấp chưa được đăng ký. Mã thông báo đăng ký hợp lệ trước đó có thể bị huỷ đăng ký vì nhiều lý do, bao gồm:
|
messaging/invalid-package-name |
Thông báo được gửi đến một mã thông báo đăng ký có tên gói không khớp với tuỳ chọn
restrictedPackageName được cung cấp.
|
messaging/message-rate-exceeded |
Tỷ lệ tin nhắn đến một mục tiêu cụ thể quá cao. Giảm số lượng thông báo được gửi đến thiết bị hoặc chủ đề này và không thử gửi lại ngay đến mục tiêu này. |
messaging/device-message-rate-exceeded |
Tỷ lệ tin nhắn đến một thiết bị cụ thể quá cao. Giảm số lượng tin nhắn được gửi đến thiết bị này và không thử gửi lại ngay đến thiết bị này. |
messaging/topics-message-rate-exceeded |
Tỷ lệ tin nhắn gửi đến người đăng ký một chủ đề cụ thể quá cao. Giảm số lượng thông báo được gửi cho chủ đề đó và không thử gửi lại ngay cho chủ đề đó. |
messaging/topics-subscription-rate-exceeded |
Tỷ lệ yêu cầu quản lý gói thuê bao đối với một chủ đề cụ thể quá cao. Hãy giảm số lượng yêu cầu được gửi cho chủ đề đó và đừng thử lại yêu cầu ngay lập tức. |
messaging/too-many-topics |
Mã thông báo đăng ký đã được đăng ký vào số lượng chủ đề tối đa và không thể đăng ký thêm nữa. |
messaging/invalid-apns-credentials |
Không gửi được thông báo nhắm đến một thiết bị Apple vì chứng chỉ SSL APN bắt buộc chưa được tải lên hoặc đã hết hạn. Kiểm tra tính hợp lệ của chứng chỉ phát triển và chứng chỉ phát hành công khai. |
messaging/mismatched-credential |
Thông tin xác thực dùng để xác thực SDK này không có quyền gửi thông báo đến thiết bị tương ứng với mã thông báo đăng ký được cung cấp. Đảm bảo thông tin xác thực và mã thông báo đăng ký đều thuộc về cùng một dự án Firebase. Hãy xem bài viết Thêm Firebase vào ứng dụng của bạn để biết tài liệu về cách xác thực Firebase Admin SDKs. |
messaging/authentication-error |
SDK không thể xác thực với máy chủ FCM. Hãy đảm bảo bạn xác thực Firebase Admin SDK bằng thông tin đăng nhập có quyền phù hợp để gửi thông báo FCM. Hãy xem bài viết Thêm Firebase vào ứng dụng của bạn để biết tài liệu về cách xác thực Firebase Admin SDKs. |
messaging/server-unavailable |
Máy chủ FCM không thể xử lý yêu cầu kịp thời. Bạn nên thử lại cùng một yêu cầu, nhưng phải:
|
messaging/internal-error |
Máy chủ FCM đã gặp lỗi khi cố gắng xử lý yêu cầu. Bạn có thể thử lại cùng một yêu cầu theo các yêu cầu được liệt kê trong hàng messaging/server-unavailable trước đó. Nếu lỗi vẫn tiếp diễn, vui lòng báo cáo vấn đề cho kênh hỗ trợ Báo cáo lỗi của chúng tôi.
|
messaging/unknown-error |
Đã xảy ra lỗi phía máy chủ không xác định. Hãy xem phản hồi thô của máy chủ trong thông báo lỗi để biết thêm thông tin chi tiết. Nếu bạn gặp lỗi này, vui lòng báo cáo toàn bộ thông báo lỗi cho kênh hỗ trợ Báo cáo lỗi của chúng tôi. |