draft out rate limit details (#3510)

* draft out rate limit details

* address comment

* backport

* remove built in

* add note

docs/apis-tools/administration-api/authentication.md

@@ -59,6 +59,22 @@ curl --header "Content-Type: application/json" \
 Access tokens have a validity period found in the access token. After this time, a new access token must be requested.
 :::
 
+## Rate limiting
+
+The OAuth service rate limits about one request per second for all clients with the same source IP address.
+
 :::note
-The auth service has built-in rate limiting. If too many token requests are executed in a short time, the client is blocked for a certain time. Since the access tokens have a certain validity period, they must be cached on the client side.
+All token requests count toward the rate limit, whether they are successful or not. If any client is running with an expired or invalid API key, that client will continually make token requests. That client will therefore exceed the rate limit for that IP address, and may block valid token requests from completing.
 :::
+
+The officially offered [client libraries](/docs/apis-tools/working-with-apis-tools.md) (as well as the Node.js and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
+
+If too many token requests are executed from the same source IP address in a short time, all token requests from that source IP address are blocked for a certain time. Since the access tokens have a 24-hour validity period, they must be cached on the client side, reused while still valid, and refreshed via a new token request once the validity period has expired.
+
+When the rate limit is triggered, the client will receive an HTTP 429 response. Note the following workarounds:
+
+- Cache the token as it is still valid for 24 hours. The official SDKs already do this by default.
+- Keep the SDK up to date. We have noted issues in older versions of the Java SDK which did not correctly cache the token.
+- Given the rate limit applies to clients with the same source IP address, be mindful of:
+  - Unexpected clients running within your infrastructure.
+  - Updating all clients to use a current API key if you delete an API key and create a new one.

docs/components/console/manage-clusters/manage-api-clients.md

@@ -18,12 +18,26 @@ For the `Client Id` and `Client Secret`, a client application can request an acc
 Access tokens have a validity period that can be found in the access token. After this time, a new access token must be requested.
 :::
 
-:::note
-The OAuth service has a built-in rate limit. If too many token requests are executed in a short time, the client is blocked for a certain time. Since the access tokens have a certain validity period, they must be cached on the client side.
+## Rate limiting
+
+The OAuth service rate limits about one request per second for all clients with the same source IP address.
 
-The officially offered [client libraries](../../../apis-tools/working-with-apis-tools.md) (as well as the Node.js client) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
+:::note
+All token requests count toward the rate limit, whether they are successful or not. If any client is running with an expired or invalid API key, that client will continually make token requests. That client will therefore exceed the rate limit for that IP address, and may block valid token requests from completing.
 :::
 
+The officially offered [client libraries](/docs/apis-tools/working-with-apis-tools.md) (as well as the Node.js and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
+
+If too many token requests are executed from the same source IP address in a short time, all token requests from that source IP address are blocked for a certain time. Since the access tokens have a 24-hour validity period, they must be cached on the client side, reused while still valid, and refreshed via a new token request once the validity period has expired.
+
+When the rate limit is triggered, the client will receive an HTTP 429 response. Note the following workarounds:
+
+- Cache the token as it is still valid for 24 hours. The official SDKs already do this by default.
+- Keep the SDK up to date. We have noted issues in older versions of the Java SDK which did not correctly cache the token.
+- Given the rate limit applies to clients with the same source IP address, be mindful of:
+  - Unexpected clients running within your infrastructure.
+  - Updating all clients to use a current API key if you delete an API key and create a new one.
+
 ## Create a client
 
 To create a client, take the following steps:

versioned_docs/version-8.4/apis-tools/administration-api/authentication.md

@@ -59,6 +59,22 @@ curl --header "Content-Type: application/json" \
 Access tokens have a validity period found in the access token. After this time, a new access token must be requested.
 :::
 
+## Rate limiting
+
+The OAuth service rate limits about one request per second for all clients with the same source IP address.
+
 :::note
-The auth service has built-in rate limiting. If too many token requests are executed in a short time, the client is blocked for a certain time. Since the access tokens have a certain validity period, they must be cached on the client side.
+All token requests count toward the rate limit, whether they are successful or not. If any client is running with an expired or invalid API key, that client will continually make token requests. That client will therefore exceed the rate limit for that IP address, and may block valid token requests from completing.
 :::
+
+The officially offered [client libraries](/docs/apis-tools/working-with-apis-tools.md) (as well as the Node.js and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
+
+If too many token requests are executed from the same source IP address in a short time, all token requests from that source IP address are blocked for a certain time. Since the access tokens have a 24-hour validity period, they must be cached on the client side, reused while still valid, and refreshed via a new token request once the validity period has expired.
+
+When the rate limit is triggered, the client will receive an HTTP 429 response. Note the following workarounds:
+
+- Cache the token as it is still valid for 24 hours. The official SDKs already do this by default.
+- Keep the SDK up to date. We have noted issues in older versions of the Java SDK which did not correctly cache the token.
+- Given the rate limit applies to clients with the same source IP address, be mindful of:
+  - Unexpected clients running within your infrastructure.
+  - Updating all clients to use a current API key if you delete an API key and create a new one.

versioned_docs/version-8.4/components/console/manage-clusters/manage-api-clients.md

@@ -18,12 +18,26 @@ For the `Client Id` and `Client Secret`, a client application can request an acc
 Access tokens have a validity period that can be found in the access token. After this time, a new access token must be requested.
 :::
 
-:::note
-The OAuth service has a built-in rate limit. If too many token requests are executed in a short time, the client is blocked for a certain time. Since the access tokens have a certain validity period, they must be cached on the client side.
+## Rate limiting
+
+The OAuth service rate limits about one request per second for all clients with the same source IP address.
 
-The officially offered [client libraries](../../../apis-tools/working-with-apis-tools.md) (as well as the Node.js client) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
+:::note
+All token requests count toward the rate limit, whether they are successful or not. If any client is running with an expired or invalid API key, that client will continually make token requests. That client will therefore exceed the rate limit for that IP address, and may block valid token requests from completing.
 :::
 
+The officially offered [client libraries](/docs/apis-tools/working-with-apis-tools.md) (as well as the Node.js and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
+
+If too many token requests are executed from the same source IP address in a short time, all token requests from that source IP address are blocked for a certain time. Since the access tokens have a 24-hour validity period, they must be cached on the client side, reused while still valid, and refreshed via a new token request once the validity period has expired.
+
+When the rate limit is triggered, the client will receive an HTTP 429 response. Note the following workarounds:
+
+- Cache the token as it is still valid for 24 hours. The official SDKs already do this by default.
+- Keep the SDK up to date. We have noted issues in older versions of the Java SDK which did not correctly cache the token.
+- Given the rate limit applies to clients with the same source IP address, be mindful of:
+  - Unexpected clients running within your infrastructure.
+  - Updating all clients to use a current API key if you delete an API key and create a new one.
+
 ## Create a client
 
 To create a client, take the following steps: