mirror of
https://github.com/zulip/zulip.git
synced 2026-07-03 21:10:12 +08:00
e9bfdd1bf2
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.
61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
# Error handling
|
|
|
|
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).
|
|
|
|
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).
|
|
|
|
Each endpoint documents its own unique errors; below, we document
|
|
errors common to many endpoints:
|
|
|
|
{generate_code_example|/rest-error-handling:post|fixture}
|
|
|
|
To help clients avoid exceeding rate limits, Zulip sets the following
|
|
HTTP headers in all API responses:
|
|
|
|
* `X-RateLimit-Remaining`: The number of additional requests of this
|
|
type that the client can send before exceeding its limit.
|
|
* `X-RateLimit-Limit`: The limit that would be applicable to a client
|
|
that had not made any recent requests of this type. This is useful
|
|
for designing a client's burst behavior so as to avoid ever reaching
|
|
a rate limit.
|
|
* `X-RateLimit-Reset`: The time at which the client will no longer
|
|
have any rate limits applied to it (and thus could do a burst of
|
|
`X-RateLimit-Limit` requests).
|
|
|
|
[Zulip's rate limiting rules are configurable][rate-limiting-rules],
|
|
and can vary by server and over time. The default configuration
|
|
currently limits:
|
|
|
|
* Every user is limited to 200 total API requests per minute.
|
|
* Separate, much lower limits for authentication/login attempts.
|
|
|
|
When the Zulip server has configured multiple rate limits that apply
|
|
to a given request, the values returned will be for the strictest
|
|
limit.
|
|
|
|
[rate-limiting-rules]: https://zulip.readthedocs.io/en/latest/production/security-model.html#rate-limiting
|
|
|
|
## 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}
|