zulip/templates/zerver/api/rest-error-handling.md

83 lines
3.0 KiB
Markdown
Raw Normal View History

# 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:
## Invalid API key
A typical failed JSON response for when the API key is invalid:
{generate_code_example|/rest-error-handling:post|fixture(400_0)}
## Missing request parameter(s)
A typical failed JSON response for when a required request parameter
is not supplied:
{generate_code_example|/rest-error-handling:post|fixture(400_1)}
## Rate limit exceeded
A typical failed JSON response for when a rate limit is exceeded:
{generate_code_example|/rest-error-handling:post|fixture(429_0)}
The `retry-after` paremeter in the response indicates how many seconds
the client must wait before making additional requests.
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, 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.
## User not authorized for query
A typical failed JSON response for when the user is not authorized for
a query:
{generate_code_example|/rest-error-handling:post|fixture(400_2)}
## User account deactivated
A typical failed json response for when user's account is deactivated:
{generate_code_example|/rest-error-handling:post|fixture(403_0)}
## Realm deactivated
A typical failed json response for when user's organization is deactivated:
{generate_code_example|/rest-error-handling:post|fixture(403_1)}