diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 3556be3e84..cd05768211 100644 --- a/api_docs/changelog.md +++ b/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 - /dev_fetch_api_key`](/api/dev-fetch-api-key): The HTTP status for - authentication errors is now 401. This was previously 403. -* All API endpoints now use the HTTP 401 error status for API requests - involving a deactivated user or realm. This was previously 403. +* [`POST /fetch_api_key`](/api/fetch-api-key), + [`POST /dev_fetch_api_key`](/api/dev-fetch-api-key): The HTTP status + for authentication errors is now 401. These previously used the HTTP + 403 error status. +* [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 diff --git a/api_docs/rest-error-handling.md b/api_docs/rest-error-handling.md index 9191b223d5..b1ce720bde 100644 --- a/api_docs/rest-error-handling.md +++ b/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 -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). +(200 = success, 4xx = user error, 5xx = server error). -For some common errors, Zulip provides a `code` attribute. Where -present, clients should check `code`, rather than `msg`, when looking -for specific error conditions, since the `msg` strings are +Every response, both success and error responses, will contain at least +two keys: + +- `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 -errors common to many endpoints: +!!! tip "" + + 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 diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 673e1f5edd..f824b813f3 100644 --- a/zerver/openapi/zulip.yaml +++ b/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 - before Zulip 5.0 (feature level 76). + A typical failed json response for when user's account is deactivated. - 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 - - The `retry-after` parameter in the response indicates how many seconds - the client must wait before making additional requests. + ### Rate limit exceeded + 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 - before Zulip 5.0 (feature level 76). + A typical failed json response for when user's organization is deactivated. - 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"