wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1373 from turt2live/travis/better-errors

Browse source 
Spell out rate limit error schema & give all errors schemas
This commit is contained in:
Travis Ralston 2018-07-18 09:00:53 -06:00 • committed by GitHub
commit 2e5f530cca
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
28 changed files with 134 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

42
api/application-service/application_service.yaml
View file

@ -131,7 +131,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
@ -140,7 +140,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |-
The application service indicates that this room alias does not exist.
@ -150,7 +150,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
"/users/{userId}":
get:
summary: Query if a user should exist on the application service.
@ -187,7 +187,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
@ -196,7 +196,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |-
The application service indicates that this user does not exist.
@ -206,7 +206,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
@ -236,7 +236,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
@ -245,7 +245,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No protocol was found with the given path.
examples:
@ -253,7 +253,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
@ -289,7 +289,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
@ -298,7 +298,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No users were found with the given parameters.
examples:
@ -306,7 +306,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location/{protocol}":
get:
summary: Retreive Matrix-side portal rooms leading to a third party location.
@ -340,7 +340,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
@ -349,7 +349,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
@ -357,7 +357,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
@ -385,7 +385,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
@ -394,7 +394,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
@ -402,7 +402,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
@ -429,7 +429,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
@ -438,7 +438,7 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
@ -446,4 +446,4 @@ paths:
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/error.yaml
$ref: ../client-server/definitions/errors/error.yaml

2
api/client-server/administrative_contact.yaml
View file

@ -129,6 +129,8 @@ paths:
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- User data
"/account/3pid/email/requestToken":

4
api/client-server/banning.yaml
View file

@ -83,6 +83,8 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership
"/rooms/{roomId}/unban":
@ -134,5 +136,7 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership

12
api/client-server/content-repo.yaml
View file

@ -72,7 +72,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/download/{serverName}/{mediaId}":
@ -120,7 +120,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/download/{serverName}/{mediaId}/{fileName}":
@ -175,7 +175,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/thumbnail/{serverName}/{mediaId}":
@ -241,7 +241,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/preview_url":
@ -296,7 +296,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/config":
@ -336,7 +336,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/error.yaml"
tags:
- Media

2
api/client-server/create_room.yaml
View file

@ -216,6 +216,8 @@ paths:
invalid: for example, the user's ``power_level`` is set below
that necessary to set the room name (``errcode`` set to
``M_INVALID_ROOM_STATE``).
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room creation

2
api/client-server/definitions/error.yaml → api/client-server/definitions/errors/error.yaml
View file

@ -17,7 +17,9 @@ properties:
errcode:
type: string
description: An error code.
example: M_UNKNOWN
error:
type: string
description: A human-readable error message.
example: An unknown error occurred
required: ["errcode"]

32
api/client-server/definitions/errors/rate_limited.yaml Normal file
View file

@ -0,0 +1,32 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
$ref: error.yaml
type: object
description: The rate limit was reached for this request
properties:
errcode:
type: string
description: The M_LIMIT_EXCEEDED error code
example: M_LIMIT_EXCEEDED
error:
type: string
description: A human-readable error message.
example: Too many requests
retry_after_ms:
type: integer
description: |-
The amount of time in milliseconds the client should wait
before trying the request again.
example: 2000
required: ["errcode"]

4
api/client-server/directory.yaml
View file

@ -68,6 +68,8 @@ paths:
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
get:
@ -118,6 +120,8 @@ paths:
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:matrix.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
delete:

4
api/client-server/inviting.yaml
View file

@ -93,9 +93,11 @@ paths:
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

8
api/client-server/joining.yaml
View file

@ -110,10 +110,12 @@ paths:
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership
"/join/{roomIdOrAlias}":
@ -215,9 +217,11 @@ paths:
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

2
api/client-server/kicking.yaml
View file

@ -87,5 +87,7 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership

6
api/client-server/leaving.yaml
View file

@ -64,7 +64,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership
"/rooms/{roomId}/forget":
@ -107,10 +107,10 @@ paths:
"error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
}
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

4
api/client-server/list_public_rooms.yaml
View file

@ -59,6 +59,8 @@ paths:
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
put:
summary: Sets the visibility of a room in the room directory
description: |-
@ -107,6 +109,8 @@ paths:
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
"/publicRooms":
get:
summary: Lists the public rooms on the server.

8
api/client-server/login.yaml
View file

@ -61,7 +61,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management
post:
@ -167,15 +167,19 @@ paths:
"errcode": "M_UNKNOWN",
"error": "Bad login type."
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: |-
The login attempt failed. For example, the password may have been incorrect.
examples:
application/json: {
"errcode": "M_FORBIDDEN"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management

8
api/client-server/presence.yaml
View file

@ -75,7 +75,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Presence
get:
@ -123,6 +123,8 @@ paths:
description: |-
There is no presence state for this user. This user may not exist or
isn't exposing presence information to you.
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: You are not allowed to see this user's presence status.
examples:
@ -131,7 +133,7 @@ paths:
"error": "You are not allowed to see their presence"
}
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/error.yaml"
tags:
- Presence
"/presence/list/{userId}":
@ -187,7 +189,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Presence
get:

4
api/client-server/profile.yaml
View file

@ -67,7 +67,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
get:
@ -141,7 +141,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
get:

4
api/client-server/pusher.yaml
View file

@ -228,10 +228,10 @@ paths:
"errcode": "M_MISSING_PARAM"
}
schema:
type: object
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Push notifications

4
api/client-server/pushrules.yaml
View file

@ -438,11 +438,11 @@ paths:
"errcode": "M_UNKNOWN"
}
schema:
type: object
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}/enabled":

2
api/client-server/receipts.yaml
View file

@ -76,6 +76,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room participation

14
api/client-server/registration.yaml
View file

@ -177,6 +177,8 @@ paths:
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
@ -185,7 +187,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/register/email/requestToken":
@ -249,7 +251,7 @@ paths:
"error": "The specified address is already in use"
}
schema:
type: object
"$ref": "definitions/errors/error.yaml"
"/account/password":
post:
summary: "Changes a user's password."
@ -296,7 +298,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/account/password/email/requestToken":
@ -363,7 +365,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/register/available":
@ -420,9 +422,11 @@ paths:
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

2
api/client-server/search.yaml
View file

@ -367,6 +367,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Search

10
api/client-server/third_party_lookup.yaml
View file

@ -66,7 +66,7 @@ paths:
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/error.yaml
$ref: definitions/errors/error.yaml
"/thirdparty/location/{protocol}":
get:
summary: Retreive Matrix-side portals rooms leading to a third party location.
@ -105,7 +105,7 @@ paths:
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/error.yaml
$ref: definitions/errors/error.yaml
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
@ -138,7 +138,7 @@ paths:
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/error.yaml
$ref: definitions/errors/error.yaml
"/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
@ -165,7 +165,7 @@ paths:
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/error.yaml
$ref: definitions/errors/error.yaml
"/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
@ -191,4 +191,4 @@ paths:
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/error.yaml
$ref: definitions/errors/error.yaml

4
api/client-server/third_party_membership.yaml
View file

@ -126,9 +126,11 @@ paths:
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

2
api/client-server/typing.yaml
View file

@ -82,6 +82,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room participation

2
api/client-server/users.yaml
View file

@ -95,6 +95,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

2
api/client-server/voip.yaml
View file

@ -73,6 +73,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- VOIP

6
api/client-server/whoami.yaml
View file

@ -65,7 +65,7 @@ paths:
"error": "Unrecognised access token."
}
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/error.yaml"
403:
description:
The appservice cannot masquerade as the user or has not registered them.
@ -75,10 +75,10 @@ paths:
"error": "Application service has not registered this user."
}
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

1
changelogs/client_server/newsfragments/1373.clarification Normal file
View file

@ -0,0 +1 @@
Describe the rate limit error response schema