api_documentation: Update rate limit error description.

Moves details about the rate limit error object and handling to
the OpenAPI documentation description for that common error.

Previously, this information was on the general rest error
handling documentation page without clear connection to the
specific rate limit error.

Fixes a typo in the changelog (feature 36) for that same error
and also fixes a misplaced colon in the description of the error
for missing request parameters.

templates/zerver/api/changelog.md

@@ -590,7 +590,7 @@ field with an integer field `invite_to_realm_policy`.
 * [`POST /users`](/api/create-user): Restricted access to organization
   administrators with the `can_create_users` permission.
 * [Error handling](/api/rest-error-handling): The `code` property will
-  not be present in errors due to rate limits.
+  now be present in errors due to rate limits.
 
 **Feature level 35**
 

templates/zerver/api/rest-error-handling.md

@@ -19,9 +19,6 @@ errors common to many endpoints:
 
 {generate_code_example|/rest-error-handling:post|fixture}
 
-The `retry-after` parameter in the response indicates how many seconds
-the client must wait before making additional requests.
-
 To help clients avoid exceeding rate limits, Zulip sets the following
 HTTP headers in all API responses:
 
@@ -44,6 +41,3 @@ and over time. The default configuration currently limits:
 When the Zulip server has configured multiple rate limits that apply
 to a given request, the values returned will be for the strictest
 limit.
-
-**Changes**: The `code` field in the response is new in Zulip 4.0
-(feature level 36).

zerver/openapi/zulip.yaml

@@ -15190,8 +15190,8 @@ components:
           description: |
             ## Missing request parameter(s)
 
-            A typical failed JSON response for when a required request parameter:
-            is not supplied
+            A typical failed JSON response for when a required request parameter
+            is not supplied:
           properties:
             result: {}
             msg: {}
@@ -15250,6 +15250,12 @@ components:
           description: |
             ## Rate limit exceeded
 
+            The `retry-after` parameter in the response indicates how many seconds
+            the client must wait before making additional requests.
+
+            **Changes**: The `code` field was not present in rate
+            limit errors before Zulip 4.0 (feature level 36).
+
             A typical failed JSON response for when a rate limit is exceeded:
     RealmDeactivatedError:
       allOf: