api-docs: Clarify error response keys and handling documentation.

Updates the main description of the API error handling article so
that the `code` key in the error reponse is more accurate.

Adds a bullet point to the API changelog for feature level 76 about
the `code` key being consistently in all error responses. This is
based on commit 8b9011dff8, which completed the migration to
JsonableError, at which point the API feature level was already
set to 75 and not yet set to 76.

Also, revises the other error related feature level 76 entries in
the API changelog.

Adds a header for  the common, shared error responses that are
documented on the error handling page, and updates those error
descriptions to include information about any extra fields and to
end with any changes notes.

api_docs/changelog.md

@@ -1699,11 +1699,17 @@ No changes; feature level used for Zulip 5.0 release.
 
 **Feature level 76**
 
-* [`POST /fetch_api_key`](/api/fetch-api-key), [`POST
+* [`POST /fetch_api_key`](/api/fetch-api-key),
-  /dev_fetch_api_key`](/api/dev-fetch-api-key): The HTTP status for
+  [`POST /dev_fetch_api_key`](/api/dev-fetch-api-key): The HTTP status
-  authentication errors is now 401. This was previously 403.
+  for authentication errors is now 401. These previously used the HTTP
-* All API endpoints now use the HTTP 401 error status for API requests
+  403 error status.
-  involving a deactivated user or realm. This was previously 403.
+* [Error handling](/api/rest-error-handling#common-error-responses): API
+  requests that involve a deactivated user or organization now use the
+  HTTP 401 error status. These previously used the HTTP 403 error status.
+* [Error handling](/api/rest-error-handling): All error responses
+  now include a `code` key with a machine-readable string value. The
+  default value for this key is `"BAD_REQUEST"` for general error
+  responses.
 * Mobile push notifications now include the `mentioned_user_group_id`
   and `mentioned_user_group_name` fields when a user group containing
   the user is mentioned.  Previously, these were indistinguishable

api_docs/rest-error-handling.md

@@ -2,20 +2,48 @@
 
 Zulip's API will always return a JSON format response.
 The HTTP status code indicates whether the request was successful
-(200 = success, 40x = user error, 50x = server error).  Every response
+(200 = success, 4xx = user error, 5xx = server error).
-will contain at least two keys: `msg` (a human-readable error message)
-and `result`, which will be either `error` or `success` (this is
-redundant with the HTTP status code, but is convenient when printing
-responses while debugging).
 
-For some common errors, Zulip provides a `code` attribute.  Where
+Every response, both success and error responses, will contain at least
-present, clients should check `code`, rather than `msg`, when looking
+two keys:
-for specific error conditions, since the `msg` strings are
+
+- `msg`: an internationalized, human-readable error message string.
+
+- `result`: either `"error"` or `"success"`, which is redundant with the
+  HTTP status code, but is convenient when print debugging.
+
+Every error response will also contain an additional key:
+
+- `code`: a machine-readable error string, with a default value of
+  `"BAD_REQUEST"` for general errors.
+
+Clients should always check `code`, rather than `msg`, when looking for
+specific error conditions. The string values for `msg` are
 internationalized (e.g. the server will send the error message
-translated into French if the user has a French locale).
+translated into French if the user has a French locale), so checking
+those strings will result in buggy code.
 
-Each endpoint documents its own unique errors; documented below are
+!!! tip ""
-errors common to many endpoints:
+
+     If a client needs information that is only present in the string value
+     of `msg` for a particular error response, then the developers
+     implementing the client should [start a conversation here][api-design]
+     in order to discuss getting a specific error `code` and/or relevant
+     additional key/value pairs for that error response.
+
+In addition to the keys described above, some error responses will
+contain other keys with further details that are useful for clients. The
+specific keys present depend on the error `code`, and are documented at
+the API endpoints where these particular errors appear.
+
+**Changes**: Before Zulip 5.0 (feature level 76), all error responses
+did not contain a `code` key, and its absence indicated that no specific
+error `code` had been allocated for that error.
+
+## Common error responses
+
+Documented below are some error responses that are common to many
+endpoints:
 
 {generate_code_example|/rest-error-handling:post|fixture}
 
@@ -32,3 +60,5 @@ configure a new feature while connected to an older Zulip server that
 does not support said feature.
 
 {generate_code_example|/settings:patch|fixture}
+
+[api-design]: https://chat.zulip.org/#narrow/channel/378-api-design

zerver/openapi/zulip.yaml

@@ -22106,9 +22106,9 @@ components:
               "result": "error",
             }
           description: |
-            ## Invalid API key
+            ### Invalid API key
 
-            A typical failed JSON response for when the API key is invalid:
+            A typical failed JSON response for when the API key is invalid.
     InvitationFailedError:
       allOf:
         - $ref: "#/components/schemas/CodedErrorBase"
@@ -22149,10 +22149,12 @@ components:
         - $ref: "#/components/schemas/CodedErrorBase"
         - additionalProperties: false
           description: |
-            ## Missing request parameter(s)
+            ### Missing request parameter
 
             A typical failed JSON response for when a required request parameter
-            is not supplied:
+            is not supplied.
+
+            The value of `var_name` contains information about the missing parameter.
           properties:
             result: {}
             msg: {}
@@ -22173,10 +22175,13 @@ components:
         - $ref: "#/components/schemas/CodedErrorBase"
         - additionalProperties: false
           description: |
-            ## Incompatible request parameters
+            ### Incompatible request parameters
 
             A typical failed JSON response for when two or more, optional
             parameters are supplied that are incompatible with each other.
+
+            The value of `parameters` in the response is string containing
+            the parameters, separated by commas, that are incompatible.
           properties:
             result: {}
             msg: {}
@@ -22203,10 +22208,10 @@ components:
               "result": "error",
             }
           description: |
-            ## User not authorized for query
+            ### User not authorized for query
 
             A typical failed JSON response for when the user is not authorized for
-            a query:
+            a query.
     UserDeactivatedError:
       allOf:
         - $ref: "#/components/schemas/CodedError"
@@ -22217,30 +22222,30 @@ components:
               "result": "error",
             }
           description: |
-            ## User account deactivated
+            ### User account deactivated
 
-            **Changes**: These errors used the HTTP 403 status code
+            A typical failed json response for when user's account is deactivated.
-            before Zulip 5.0 (feature level 76).
 
-            A typical failed json response for when user's account is deactivated:
+            **Changes**: As of Zulip 5.0 (feature level 76), these errors use the
+            HTTP 401 status code. Before this feature level, they used the HTTP 403
+            status code.
     RateLimitedError:
       allOf:
         - $ref: "#/components/schemas/CodedErrorBase"
         - additionalProperties: false
           description: |
-            ## Rate limit exceeded
+            ### Rate limit exceeded
-
-            The `retry-after` parameter in the response indicates how many seconds
-            the client must wait before making additional requests.
 
+            A typical failed JSON response for when a rate limit is exceeded.
             Zulip sets a few [HTTP response headers][rate-limit-headers]
             to help with preventing rate limit errors.
 
+            The value of `retry-after` 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:
-
             [rate-limit-headers]: /api/http-headers#rate-limiting-response-headers
           properties:
             result: {}
@@ -22268,12 +22273,13 @@ components:
               "result": "error",
             }
           description: |
-            ## Realm deactivated
+            ### Realm deactivated
 
-            **Changes**: These errors used the HTTP 403 status code
+            A typical failed json response for when user's organization is deactivated.
-            before Zulip 5.0 (feature level 76).
 
-            A typical failed json response for when user's organization is deactivated:
+            **Changes**: As of Zulip 5.0 (feature level 76), these errors use the
+            HTTP 401 status code. Before this feature level, they used the HTTP 403
+            status code.
     InvalidPushDeviceTokenError:
       allOf:
         - $ref: "#/components/schemas/CodedError"