Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/api_docs/rest-error-handling.md

65 lines
2.5 KiB
Markdown
Raw Normal View History

docs: Fix capitalization mistakes. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-05-10 07:02:14 +02:00
# Error handling
/api: Expand "common errors" page to more generally cover error handling.
2018-04-17 00:42:34 +02:00
api docs: Make minor copyediting changes.
2018-09-26 04:28:29 +02:00
Zulip's API will always return a JSON format response.
The HTTP status code indicates whether the request was successful
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.
2024-06-17 16:55:37 +02:00
(200 = success, 4xx = user error, 5xx = server error).
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
api-docs: Add comma to all uses of "e.g." in API docs.
2024-07-04 12:14:37 +02:00
internationalized (e.g., the server will send the error message
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.
2024-06-17 16:55:37 +02:00
translated into French if the user has a French locale), so checking
those strings will result in buggy code.
/api: Expand "common errors" page to more generally cover error handling.
2018-04-17 00:42:34 +02:00
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.
2024-06-17 16:55:37 +02:00
!!! 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:
/api: Expand "common errors" page to more generally cover error handling.
2018-04-17 00:42:34 +02:00
openapi: Render all responses of an operation. Previously, one needed to specifying all the HTTP status codes that we want to render along with the operation, but the primary use case just needs the responses of all the status codes, and not just one. This commit modifies the Markdown extension to render all the responses of all status codes of a specified operation in a loop.
2021-07-13 17:33:43 +02:00
{generate_code_example|/rest-error-handling:post|fixture}
api docs: Document rate limiting rules. Unfortunately, the example doesn't work due to some sort of bug with the fixture generation system, which I've reported as #19072.
2021-06-30 22:03:22 +02:00
response: Implement ignored parameters with MutableJsonResponse class. Creates `MutableJsonResponse` as a subclass of Django's `HttpResponse` that we can modify for ignored parameters in the response content. Updates responses to include `ignored_parameters_unsupported` in the response data through `has_request_variables`. Creates unit test for this implementation in `test_decorators.py`. The `method` parameter processed in `rest_dispatch` is not in the `REQ` framework, so for any tests that pass that parameter, assert for the ignored parameter with a comment. Updates OpenAPI documentation for `ignored_parameters_unsupported` being returned in the JSON success response for all endpoints. Adds detailed documentation in the error handling article, and links to that page in relevant locations throughout the API docs. For the majority of endpoints, the documentation does not include the array in any examples of return values, and instead links to the error handling page. The exceptions are the three endpoints that had previously supported this return value. The changes note and example for these endpoints is also used in the error handling page.
2022-08-25 18:41:46 +02:00
## Ignored Parameters
In JSON success responses, all Zulip REST API endpoints may return
an array of parameters sent in the request that are not supported
by that specific endpoint.
api-docs: Add comma to all uses of "e.g." in API docs.
2024-07-04 12:14:37 +02:00
While this can be expected, e.g., when sending both current and legacy
response: Implement ignored parameters with MutableJsonResponse class. Creates `MutableJsonResponse` as a subclass of Django's `HttpResponse` that we can modify for ignored parameters in the response content. Updates responses to include `ignored_parameters_unsupported` in the response data through `has_request_variables`. Creates unit test for this implementation in `test_decorators.py`. The `method` parameter processed in `rest_dispatch` is not in the `REQ` framework, so for any tests that pass that parameter, assert for the ignored parameter with a comment. Updates OpenAPI documentation for `ignored_parameters_unsupported` being returned in the JSON success response for all endpoints. Adds detailed documentation in the error handling article, and links to that page in relevant locations throughout the API docs. For the majority of endpoints, the documentation does not include the array in any examples of return values, and instead links to the error handling page. The exceptions are the three endpoints that had previously supported this return value. The changes note and example for these endpoints is also used in the error handling page.
2022-08-25 18:41:46 +02:00
names for a parameter to a Zulip server of unknown version, this often
indicates either a bug in the client implementation or an attempt to
configure a new feature while connected to an older Zulip server that
does not support said feature.
{generate_code_example|/settings:patch|fixture}
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.
2024-06-17 16:55:37 +02:00
[api-design]: https://chat.zulip.org/#narrow/channel/378-api-design