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:
{
"msg": "Invalid API key",
"result": "error"
}
Missing request parameter(s)
A typical failed JSON response for when a required request parameter
is not supplied:
{
"code": "REQUEST_VARIABLE_MISSING",
"msg": "Missing 'content' argument",
"result": "error",
"var_name": "content"
}
User not authorized for query
A typical failed JSON response for when the user is not authorized for
a query:
{
"code": "BAD_REQUEST",
"msg": "User not authorized for this query",
"result": "error"
}
User account deactivated
Changes: These errors used the HTTP 403 status code
before Zulip 5.0 (feature level 76).
A typical failed json response for when user's account is deactivated:
{
"code": "USER_DEACTIVATED",
"msg": "Account is deactivated",
"result": "error"
}
Realm deactivated
Changes: These errors used the HTTP 403 status code
before Zulip 5.0 (feature level 76).
A typical failed json response for when user's organization is deactivated:
{
"code": "REALM_DEACTIVATED",
"msg": "This organization is deactivated",
"result": "error"
}
Rate limit exceeded
The retry-after
parameter in the response indicates how many seconds
the client must wait before making additional requests.
Changes: The code
field was not present in rate
limit errors before Zulip 4.0 (feature level 36).
A typical failed JSON response for when a rate limit is exceeded:
{
"code": "RATE_LIMIT_HIT",
"msg": "API usage exceeded rate limit",
"result": "error",
"retry-after": 28.706807374954224
}
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.