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

35 lines
1.4 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: Expand "common errors" page to more generally cover error handling.
2018-04-17 00:42:34 +02:00
(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).
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
internationalized (e.g. the server will send the error message
translated into French if the user has a French locale).
api_docs: Add page documenting HTTP headers in the api docs. Adds a page to the general api documentation about HTTP headers, so that information about the special response headers for rate limits have a more logical location in the docs and so that other HTTP header information can be shared, such as `User-Agent` conventions. Adjusts some text and linking on the rest-error-handling page and overview page for the REST API for the addition of the HTTP headers page.
2022-01-24 16:55:05 +01:00
Each endpoint documents its own unique errors; documented below are
/api: Expand "common errors" page to more generally cover error handling.
2018-04-17 00:42:34 +02:00
errors common to many endpoints:
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.
While this can be expected, e.g. when sending both current and legacy
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}