FCM エラーコード

HTTP v1 API の REST エラーコード

HTTP v1 API の HTTP エラー レスポンスには、エラーコード、エラー メッセージ、エラー ステータスが含まれます。また、エラーの詳細を含む 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"
      }
    ]
   }
}

どちらのメッセージもコードとステータスは同じですが、details 配列に異なるタイプの値が含まれています。最初の例は type.googleapis.com/google.rpc.BadRequest というタイプで、リクエスト値のエラーを示します。2 番目の例は type.googleapis.com/google.firebase.fcm.v1.FcmError というタイプで、FCM 固有のエラーを示します。多くのエラーの場合、details 配列にデバッグして解決策を見つけるために必要な情報が含まれています。

次の表に、FCM v1 REST API のエラーコードとその説明を示しています。

エラーコード 説明と解決手順
UNSPECIFIED_ERROR このエラーに関する詳細情報はありません。 なし
INVALID_ARGUMENT（HTTP エラーコード = 400）リクエスト パラメータが無効でした。無効なフィールドを指定するために、google.rpc.BadRequest タイプの拡張機能が返されます。 考えられる原因としては、無効な登録、無効なパッケージ名、大きすぎるメッセージ、無効なデータキー、無効な TTL、その他の無効なパラメータなどがあります。
登録が無効です: サーバーに渡す登録トークンの形式を確認します。登録トークンが、FCM への登録時にクライアント アプリが受信した登録トークンと一致していることを確認します。トークンを切り捨てたり、文字を追加したりしないでください。
パッケージ名が無効です: メッセージの宛先が、リクエストで渡された値と一致するパッケージ名を持つ登録トークンに指定されていることを確認します。
メッセージが大きすぎる: メッセージに含まれているペイロード データの合計サイズが FCM の上限を超えていないことを確認します。上限サイズは、ほとんどのメッセージでは 4,096 バイト、トピック メッセージの場合は 2,048 バイトです。これには、キーと値の両方が含まれます。
データキーが無効: ペイロード データに、FCM 内部で使用されるキー（from、gcm、google という接頭辞が付いた値など）が含まれていないことを確認します。一部の語（collapse_key など）は FCM でも使用されますが、ペイロードでも使用できます。この場合、ペイロードの値は FCM の値でオーバーライドされます。
TTL が無効です: ttl で使用される値が、0～2,419,200（4 週間）の期間（秒単位）を示す整数であることを確認します。
無効なパラメータ: 指定されたパラメータの名前と型が正しいことを確認します。
UNREGISTERED（HTTP エラーコード = 404）アプリ インスタンスが FCM から登録解除されました。通常、使用されているトークンが無効であるため、新しいトークンを使用する必要があります。 このエラーは、登録トークンがないか、登録されていないトークンが原因で発生することがあります。
登録がない: メッセージのターゲットが token 値の場合は、リクエストに登録トークンが含まれていることを確認します。
未登録: 次のようないくつかの状況では、既存の登録トークンが有効でなくなることがあります。
- クライアント アプリが FCM から登録解除した場合。
クライアント アプリが自動的に登録解除された場合。これはユーザーがアプリケーションをアンインストールしたときに発生する可能性があります。たとえば iOS で、APNs フィードバック サービスによって APNs トークンが無効であると報告された場合です。
登録トークンが期限切れになった場合（たとえば、Google が登録トークンを更新する場合、iOS デバイスの APNs トークンが期限切れになった場合）。
クライアント アプリが更新されたが、新しいバージョンはメッセージを受信するように構成されていない場合。
上記のすべての状況で、アプリサーバーから既存の登録トークンを削除し、これを使用したメッセージの送信を停止してください。
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）APN 証明書またはウェブプッシュ認証キーが無効であるか、存在しません。 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 プラットフォームで APNs フィードバック サービスによって APNs トークンが無効であると報告された場合に起こる可能性があります。
  • 登録トークンの有効期限が切れた。たとえば、Google が登録トークンの更新を決定したり、Apple デバイスの APNs トークンが期限切れになったりする場合があります。
  • クライアント アプリが更新されたが、新しいバージョンがメッセージを受信するように構成されていない。
このような場合は、該当する登録トークンを削除し、その登録トークンを使用したメッセージの送信を中止します。
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 必要な APNs 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　サーバーで時間内にリクエストを処理できませんでした。同じリクエストを再試行しますが、次のことに注意してください。
  • FCM 接続サーバーからのレスポンスに Retry-After ヘッダーが含まれている場合は、それに従います。
  • 再試行メカニズムに指数バックオフを実装します。たとえば、1 秒後に最初の再試行を行った場合は、次の試行まで少なくとも 2 秒待ち、その次の再試行まで少なくとも 4 秒待ち、秒数のインターバルを上げていきます。複数のメッセージを再送信する場合は、すべてのメッセージの新規リクエストが同時に発行されないように、ランダムな秒数を加えて各メッセージの送信を個別に遅らせます。
問題を引き起こす送信者はブラックリストに登録されるおそれがあります。
messaging/internal-error リクエストを処理しようとして　FCM　サーバーでエラーが発生しました。前の messaging/server-unavailable の項目に記載されている要件に従って同じリクエストを再試行できます。エラーが解決しない場合は、バグレポートに問題を報告してください。
messaging/unknown-error 不明なサーバーエラーが返されました。詳細については、エラー メッセージに含まれる生のサーバー レスポンスをご覧ください。このエラーが発生した場合は、完全なエラー メッセージをバグレポートに報告してください。