errors: add 40183 and 103011 for FCM topics

errors/codes/103011.md

@@ -0,0 +1,22 @@
+---
+code: 103011
+identifier: push_rate_limited_by_provider
+title: Push request rate limited by provider
+summary: A push request was not completed because the push provider rejected it for exceeding a rate limit. FCM, for example, limits changes to topic subscriptions across each Firebase project, so the condition is usually temporary.
+---
+
+## What you should do
+
+Retry the request after a delay, backing off exponentially with jitter between attempts. When the response has a `Retry-After` header, wait at least that long.
+
+When a request subscribes many devices at once, for example every device for a client ID, Ably retries the devices that were rate limited itself, so there is nothing to retry.
+
+If the error persists, the requests sent to the provider are consistently above its limit. Spread the requests out over time rather than sending them in a burst.
+
+## Why it happens
+
+Push providers limit how quickly requests can be made. FCM, for example, limits the rate of topic subscription changes for each Firebase project, so every app and device using the same project shares the limit. A burst of requests, such as many devices subscribing to a topic at once, can exceed it.
+
+## What you'll see
+
+The error is reported with code 103011 and HTTP status 429. The message names the operation that was limited, such as `fcm subscribe: rate limited; retry with backoff`, followed by the provider's own message.

errors/codes/40183.md

@@ -0,0 +1,18 @@
+---
+code: 40183
+identifier: fcm_service_account_required_for_topics
+title: FCM service account required for FCM topics
+summary: An FCM topics request was refused because FCM topics require the app's FCM credentials to be a service account, but the app is configured only with a legacy FCM server key.
+---
+
+## What you should do
+
+[Configure the app's FCM credentials](https://ably.com/docs/push/configure/device?lang=java#fcm) with a Firebase service account key, in place of the legacy server key. Upload the key's JSON file in the app's [notification settings](https://ably.com/accounts/any/apps/any/notifications), or with the [Ably CLI](https://ably.com/docs/cli/push/config/set-fcm). The request then succeeds without any other change. Retrying the request does not help while the app has only a server key.
+
+## Why it happens
+
+FCM topics are managed and sent to through the FCM HTTP v1 APIs, which authenticate with a service account. A legacy server key can't be used with them, so Ably refuses the request before contacting FCM rather than failing it later.
+
+## What you'll see
+
+The error is reported with code 40183 and HTTP status 400. The message is `unable to use FCM topics; FCM topics require the app's FCM credentials to be a service account, not a legacy server key`.

protocol/errors.json

@@ -402,6 +402,11 @@
       "title": "APNs token authentication required for push-to-start Live Activities notification",
       "summary": "A live-activity push-to-start notification was not sent because push-to-start requires the app's APNs credentials to use token-based authentication, but the app is not configured that way."
     },
+    "40183": {
+      "identifier": "fcm_service_account_required_for_topics",
+      "title": "FCM service account required for FCM topics",
+      "summary": "An FCM topics request was refused because FCM topics require the app's FCM credentials to be a service account, but the app is configured only with a legacy FCM server key."
+    },
     "40300": {
       "identifier": "forbidden",
       "title": "Forbidden",
@@ -1322,6 +1327,11 @@
       "title": "Push recipient endpoint invalid",
       "summary": "The push notification was not delivered because the endpoint in the device's push recipient is not one Ably will send to. A web push endpoint has to be an https address that resolves to a publicly reachable host."
     },
+    "103011": {
+      "identifier": "push_rate_limited_by_provider",
+      "title": "Push request rate limited by provider",
+      "summary": "A push request was not completed because the push provider rejected it for exceeding a rate limit. FCM, for example, limits changes to topic subscriptions across each Firebase project, so the condition is usually temporary."
+    },
     "104000": {
       "identifier": "streamed_message_finalize_failed",
       "title": "Streamed message could not be finalized",