mirror of
https://github.com/zulip/zulip.git
synced 2025-11-05 22:43:42 +00:00
d0c25a9291
Updates the main description of the API error handling article so
that the `code` key in the error reponse is more accurate.
Adds a bullet point to the API changelog for feature level 76 about
the `code` key being consistently in all error responses. This is
based on commit 8b9011dff8, which completed the migration to
JsonableError, at which point the API feature level was already
set to 75 and not yet set to 76.
Also, revises the other error related feature level 76 entries in
the API changelog.
Adds a header for the common, shared error responses that are
documented on the error handling page, and updates those error
descriptions to include information about any extra fields and to
end with any changes notes.
65 lines
2.5 KiB
Markdown
65 lines
2.5 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, 4xx = user error, 5xx = server error).
|
|
|
|
Every response, both success and error responses, will contain at least
|
|
two keys:
|
|
|
|
- `msg`: an internationalized, human-readable error message string.
|
|
|
|
- `result`: either `"error"` or `"success"`, which is redundant with the
|
|
HTTP status code, but is convenient when print debugging.
|
|
|
|
Every error response will also contain an additional key:
|
|
|
|
- `code`: a machine-readable error string, with a default value of
|
|
`"BAD_REQUEST"` for general errors.
|
|
|
|
Clients should always check `code`, rather than `msg`, when looking for
|
|
specific error conditions. The string values for `msg` are
|
|
internationalized (e.g. the server will send the error message
|
|
translated into French if the user has a French locale), so checking
|
|
those strings will result in buggy code.
|
|
|
|
!!! tip ""
|
|
|
|
If a client needs information that is only present in the string value
|
|
of `msg` for a particular error response, then the developers
|
|
implementing the client should [start a conversation here][api-design]
|
|
in order to discuss getting a specific error `code` and/or relevant
|
|
additional key/value pairs for that error response.
|
|
|
|
In addition to the keys described above, some error responses will
|
|
contain other keys with further details that are useful for clients. The
|
|
specific keys present depend on the error `code`, and are documented at
|
|
the API endpoints where these particular errors appear.
|
|
|
|
**Changes**: Before Zulip 5.0 (feature level 76), all error responses
|
|
did not contain a `code` key, and its absence indicated that no specific
|
|
error `code` had been allocated for that error.
|
|
|
|
## Common error responses
|
|
|
|
Documented below are some error responses that are common to many
|
|
endpoints:
|
|
|
|
{generate_code_example|/rest-error-handling:post|fixture}
|
|
|
|
## 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}
|
|
|
|
[api-design]: https://chat.zulip.org/#narrow/channel/378-api-design
|