2021-05-10 07:02:14 +02:00
|
|
|
# Error handling
|
2018-04-17 00:42:34 +02:00
|
|
|
|
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
|
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).
|
|
|
|
|
|
|
|
Each endpoint documents its own unique errors; below, we document
|
|
|
|
errors common to many endpoints:
|
|
|
|
|
2021-07-13 17:33:43 +02:00
|
|
|
{generate_code_example|/rest-error-handling:post|fixture}
|
2021-06-30 22:03:22 +02:00
|
|
|
|
|
|
|
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).
|
|
|
|
|
2022-11-09 03:42:21 +01:00
|
|
|
[Zulip's rate limiting rules are configurable][rate-limiting-rules],
|
|
|
|
and can vary by server and over time. The default configuration
|
|
|
|
currently limits:
|
2021-06-30 22:03:22 +02:00
|
|
|
|
|
|
|
* 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.
|
2022-11-09 03:42:21 +01:00
|
|
|
|
|
|
|
[rate-limiting-rules]: https://zulip.readthedocs.io/en/latest/production/security-model.html#rate-limiting
|
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}
|