diff options
| author | Joas Schilling <coding@schilljs.com> | 2023-05-31 10:48:47 +0200 |
|---|---|---|
| committer | Joas Schilling <coding@schilljs.com> | 2023-06-01 06:34:49 +0200 |
| commit | d0ca6ecb89864b5b054fccbfd1afeeb35dd0e0dc (patch) | |
| tree | b4e2d87c407f76ffc4d60f6ec5f1631267cccef0 /docs | |
| parent | 67c22f97d7d9a10fe085f7bc65ee4f0c23c9e652 (diff) | |
fix(docs): Add documentation about "global" status codes and headers
Signed-off-by: Joas Schilling <coding@schilljs.com>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/global.md | 42 | ||||
| -rw-r--r-- | docs/index.md | 1 |
2 files changed, 43 insertions, 0 deletions
diff --git a/docs/global.md b/docs/global.md new file mode 100644 index 000000000..a1e728a76 --- /dev/null +++ b/docs/global.md @@ -0,0 +1,42 @@ +# Global API status and headers + +## Maintenance mode + +Server is in maintenance mode, when the header is not available it could be a missing execution of a database upgrade or any other general server failure. + +* Response: + - Status code: + + `503 Service Unavailable` + + - Header: + +| field | type | Description | +|--------------------------------|------|-------------| +| `X-Nextcloud-Maintenance-Mode` | int | Value `1` | + + +## Rate limit + +The remote address sent too many requests targeting the same endpoint, see the [Nextcloud Developer manual](https://docs.nextcloud.com//server/stable/developer_manual/basics/controllers.html#rate-limiting) for more information. + +* Response: + - Status code: + + `429 Too Many Requests` + +## Brute force protection + +The remote address sent too many requests targeting the same action, see the [Nextcloud Developer manual](https://docs.nextcloud.com//server/stable/developer_manual/basics/controllers.html#brute-force-protection) for more information. + +* Response: + - Status code: + + `429 Too Many Requests` + +## Outdated client + +From time to time it is unavoidable to break compatibility. In such cases we try to be as helpful for the users as possible and instead of behaving unexpected, a dedicated error response is returned and the clients should handle it properly and show a message that the client is outdated and needs to be upgraded in order to continue using this server. + +* Response: + - Status code: + + `426 Upgrade Required` + - Body: + + `ocs.meta.message` contains the minimum required version of the used client diff --git a/docs/index.md b/docs/index.md index e1dc99b7c..7628a7a07 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,6 +25,7 @@ ## API documentation +* [Global API status and headers](global.md) * [Conversation management](conversation.md) * [Conversation avatar management](avatar.md) * [Participant management](participant.md) |