HTTP v1 API의 REST 오류 코드
HTTP v1 API의 HTTP 오류 응답에는 오류 코드, 오류 메시지, 오류 상태가 포함됩니다. 오류에 대한 자세한 내용이 포함된 details 배열도 포함될 수 있습니다.
다음은 두 가지 샘플 오류 응답입니다.
예시 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"
}
]
}
}
두 메시지의 코드와 상태는 동일하지만 세부정보 배열에는 다른 유형의 값이 포함됩니다. 첫 번째 예에는 요청 값의 오류를 나타내는 유형 type.googleapis.com/google.rpc.BadRequest가 있습니다. 유형이 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바이트입니다. 여기에는 키와 값이 모두 포함됩니다. 잘못된 데이터 키: FCM에서 내부적으로 사용하는 키(예: from, gcm, google이 앞에 붙은 값)가 페이로드 데이터에 포함되어 있지 않은지 확인합니다. 또한 페이로드 값이 FCM 값에 의해 재정의되는 경우에는 FCM에서 사용하는 collapse_key와 같은 일부 단어가 페이로드에도 허용된다는 점에 유의하세요. 잘못된 TTL: ttl에 사용된 값이 0~2,419,200초(4주) 사이의 기간을 나타내는 정수인지 확인합니다. 잘못된 파라미터: 제공된 파라미터의 이름과 유형이 올바른지 확인합니다. |
UNREGISTERED(HTTP 오류 코드 = 404) 앱 인스턴스가 FCM에서 등록 취소되었습니다. 이는 일반적으로 사용된 토큰이 더 이상 유효하지 않으며 새 토큰을 사용해야 함을 의미합니다. |
이 오류는 등록 토큰 누락 또는 등록 취소된 토큰으로 인해 발생할 수 있습니다. 등록 누락: 메시지의 타겟이 token 값인 경우 요청에 등록 토큰이 포함되어 있는지 확인합니다.등록되지 않음: 다음을 비롯한 몇몇 상황에서는 기존 등록 토큰이 더 이상 유효하지 않게 될 수 있습니다. - 클라이언트 앱이 FCM에서 등록 해제된 경우입니다. - 클라이언트 앱이 자동으로 등록 해제되었습니다. 사용자가 애플리케이션을 제거한 경우에 발생할 수 있습니다. 예를 들어 iOS에서 APNs 피드백 서비스가 APNs 토큰이 잘못되었다고 보고한 경우입니다. - 등록 토큰이 만료되었습니다. 예를 들어 Google에서 등록 토큰 새로고침을 결정한 경우이거나 APNs 토큰이 iOS 기기에서 만료된 경우입니다. - 클라이언트 앱이 업데이트되었지만 새 버전이 메시지를 수신할 수 있도록 구성되지 않았습니다. 위와 같은 경우에는 앱 서버에서 등록 토큰을 삭제하고 더 이상 메시지 전송에 이 등록 토큰을 사용하지 마세요. |
SENDER_ID_MISMATCH(HTTP 오류 코드 = 403) 인증된 발신자 ID가 등록 토큰의 발신자 ID와 다릅니다. |
등록 토큰은 특정 발신자 그룹에 연결됩니다. 클라이언트 앱을 FCM에 등록할 때 메시지를 보낼 수 있는 발신자를 지정해야 합니다. 클라이언트 앱에 메일을 보낼 때는 발신자 ID 중 하나를 사용해야 합니다. 다른 발신자로 전환하면 기존 등록 토큰이 작동하지 않습니다. |
QUOTA_EXCEEDED(HTTP 오류 코드 = 429) 메시지 타겟의 전송 한도를 초과했습니다. 초과된 할당량을 지정하기 위해 google.rpc.QuotaFailure 유형의 확장 프로그램이 반환됩니다. |
이 오류는 메시지 속도 할당량 초과, 기기 메시지 속도 할당량 초과 또는 주제 메시지 속도 할당량 초과로 인해 발생할 수 있습니다. 메시지 속도 초과: 메시지 전송 속도가 너무 높습니다. 전반적인 메시지 전송 속도를 줄여야 합니다. 최소 초기 지연 시간이 1분인 지수 백오프를 사용하여 거부된 메시지를 다시 시도합니다. 기기 메시지 속도 초과: 특정 기기로 전달되는 메시지 속도가 너무 높습니다. 단일 기기에 대한 메시지 속도 제한을 참고하세요. 이 기기로 보내는 메시지 수를 줄이고 전송을 재시도할 때 지수 백오프를 사용하세요. 주제 메시지 속도 초과: 특정 주제의 구독자에게 전달되는 메시지 속도가 너무 높습니다. 이 주제로 보내는 메시지 수를 줄이고 최소 초기 지연 시간이 1분인 지수 백오프를 사용하여 전송을 재시도하세요. |
UNAVAILABLE(HTTP 오류 코드 = 503) 서버가 과부하되었습니다. |
서버에서 시간 내에 요청을 처리하지 못했습니다. 동일한 요청을 다시 시도하되 다음을 수행해야 합니다. - FCM 연결 서버의 응답에 포함된 경우 Retry-After 헤더를 적용합니다. - 재시도 방식에서 지수 백오프를 구현합니다. (예를 들어 첫 번째 재시도 전에 1초 동안 기다렸다면 다음에는 2초, 그 다음에는 4초 동안 기다리는 식으로 대기 시간을 점차 늘립니다.) 여러 메시지를 보내는 경우 지터링을 적용하는 것이 좋습니다. 자세한 내용은 재시도 처리를 참조하거나 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 크기 한도를 초과합니다. 대부분의 메시지는 4,096바이트로 제한됩니다. 주제로 보낸 메시지는 2,048바이트로 제한됩니다. 전체 페이로드 크기에는 키와 값이 모두 포함됩니다. |
messaging/invalid-options |
잘못된 메시지 옵션 객체가 제공되었습니다. 오류 메시지에 추가 정보가 들어 있습니다. |
messaging/invalid-registration-token |
잘못된 등록 토큰이 제공되었습니다. FCM에 등록할 때 클라이언트 앱이 수신하는 등록 토큰과 일치하는지 확인합니다. 문자를 자르거나 추가하지 마세요. |
messaging/registration-token-not-registered |
제공된 등록 토큰이 등록되지 않았습니다. 이전에 유효했던 등록 토큰이 다음을 비롯한 여러 가지 이유로 등록 취소되었을 수 있습니다.
|
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 |
필수 APN SSL 인증서가 업로드되지 않았거나 만료되어 Apple 기기를 대상으로 메시지를 보낼 수 없습니다. 개발 및 프로덕션 인증서의 유효성을 확인하세요. |
messaging/mismatched-credential |
이 SDK를 인증하는 데 사용된 인증 정보에, 제공된 등록 토큰에 해당하는 기기로 메시지를 보낼 권한이 없습니다. 인증 정보와 등록 토큰이 동일한 Firebase 프로젝트에 속하는지 확인하세요. Firebase Admin SDK 인증 방법에 관한 자세한 내용은 앱에 Firebase 추가를 참조하세요. |
messaging/authentication-error |
SDK에서 FCM 서버에 인증할 수 없습니다. 반드시 FCM 메시지를 전송할 수 있는 올바른 권한이 있는 사용자 인증 정보로 Firebase Admin SDK를 인증해야 합니다. Firebase Admin SDK 인증 방법에 관한 자세한 내용은 앱에 Firebase 추가를 참조하세요. |
messaging/server-unavailable |
FCM 서버에서 시간 내에 요청을 처리하지 못했습니다. 동일한 요청을 다시 시도하되 다음을 수행해야 합니다.
|
messaging/internal-error |
요청을 처리하려고 시도하는 중에 FCM 서버에 오류가 발생했습니다. 이전 messaging/server-unavailable 행에 나와 있는 요구사항에 따라 동일한 요청을 다시 시도할 수 있습니다. 오류가 계속되면 버그 신고 지원 채널에 문제를 신고하시기 바랍니다.
|
messaging/unknown-error |
알 수 없는 서버 오류가 반환되었습니다. 자세한 내용은 오류 메시지의 원시 서버 응답을 참조하세요. 이 오류가 발생하면 버그 신고 지원 채널에 전체 오류 메시지를 신고하세요. |