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; documented below are errors common to many endpoints:

Invalid API key

A typical failed JSON response for when the API key is invalid:

{
    "code": "INVALID_API_KEY",
    "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.

Zulip sets a few HTTP response headers to help with preventing rate limit errors.

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
}

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.

Changes: The ignored_parameters_unsupported array was added as a possible return value for all REST API endpoint JSON success responses in Zulip 7.0 (feature level 167).

Previously, it was added to POST /users/me/subscriptions/properties in Zulip 5.0 (feature level 111) and to PATCH /realm/user_settings_defaults in Zulip 5.0 (feature level 96). The feature was introduced in Zulip 5.0 (feature level 78) as a return value for the PATCH /settings endpoint.

A typical successful JSON response with ignored parameters may look like:

{
    "ignored_parameters_unsupported": [
        "invalid_param_1",
        "invalid_param_2"
    ],
    "msg": "",
    "result": "success"
}