1 files changed, 31 insertions, 7 deletions

diff --git a/support/doc/api/openapi.yaml b/support/doc/api/openapi.yaml
index 9f40d74c6..ae4855878 100644
--- a/support/doc/api/openapi.yaml
+++ b/support/doc/api/openapi.yaml
@@ -53,14 +53,30 @@ info:
     }
     ```
 
-    We provide error types for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
-    but it is still optional.
+    We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/shared/models/server/server-error-code.enum.ts),
+    but it is still optional. Types are used to disambiguate errors that bear the same status code
+    and are non-obvious:
+
+    ```
+    HTTP 1.1 403 Forbidden
+    Content-Type: application/problem+json; charset=utf-8
+
+    {
+      "detail": "Cannot get this video regarding follow constraints",
+      "docs": "https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo",
+      "status": 403,
+      "title": "Forbidden",
+      "type": "https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints"
+    }
+    ```
+
+    Here a 403 error could otherwise mean that the video is private or blocklisted.
 
     ### Validation errors
 
     Each parameter is evaluated on its own against a set of rules before the route validator
     proceeds with potential testing involving parameter combinations. Errors coming from validation
-    errors appear earlier and benefit from a more detailed error type:
+    errors appear earlier and benefit from a more detailed error description:
 
     ```
     HTTP 1.1 400 Bad Request
@@ -89,6 +105,12 @@ info:
     `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg`
     is about.
 
+    ### Deprecated error fields
+
+    Some fields could be included with previous versions. They are still included but their use is deprecated:
+    - `error`: superseded by `detail`
+    - `code`: superseded by `type` (which is now an URI)
+
     # Rate limits
 
     We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators:
@@ -932,6 +954,12 @@ paths:
                     type: integer
                     minimum: 0
                     example: 1209600
+        '400':
+          x-summary: client or credentials are invalid
+          description: |
+            Disambiguate via `type`:
+            - `invalid_client` for an unmatched `client_id`
+            - `invalid_grant` for unmatched credentials
       x-codeSamples:
         - lang: Shell
           source: |
@@ -1812,8 +1840,6 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/VideoUploadResponse'
-        '400':
-          description: invalid file field, schedule date or parameter
         '403':
           description: video didn't pass upload filter
         '408':
@@ -1918,8 +1944,6 @@ paths:
               schema:
                 type: number
                 example: 0
-        '400':
-          description: invalid file field, schedule date or parameter
         '413':
           description: video file too large, due to quota, absolute max file size or concurrent partial upload limit
         '415':