docs: add reusable OpenAPI response definitions for 400, 401, 429 error formats (#672)

Co-authored-by: Teslim Ibisomi <johndoe@example.com>

Author: alade-dev

backend/docs/openapi.yaml

@@ -32,6 +32,33 @@ components:
       bearerFormat: JWT
       description: JWT obtained from POST /api/auth/verify
 
+  responses:
+    BadRequest:
+      description: Bad Request - Invalid input, missing required fields, or malformed data
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error: Invalid signature format (must be hex or base64)
+
+    Unauthorized:
+      description: Unauthorized - Missing or invalid JWT / authentication credentials
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error: Missing authorization header
+
+    TooManyRequests:
+      description: Too Many Requests - Rate limit exceeded; retry after a short delay
+      content:
+        text/plain:
+          schema:
+            type: string
+          example: Too many requests, please try again later.
+
   schemas:
     ErrorResponse:
       type: object
@@ -538,6 +565,8 @@ paths:
                 $ref: '#/components/schemas/ChallengeResponse'
               example:
                 challenge: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
 
   /api/auth/verify:
     post:
@@ -574,6 +603,8 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
               example:
                 error: Signature verification failed
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           description: Internal server error
           content:
@@ -606,6 +637,8 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
               example:
                 error: Missing authorization header
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           description: Internal server error
           content:
@@ -641,6 +674,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           description: Internal server error
           content:
@@ -678,6 +713,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           description: Internal server error
           content:
@@ -708,6 +745,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           description: Internal server error
           content:
@@ -755,6 +794,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           description: Internal server error
           content:
@@ -810,11 +851,7 @@ paths:
                 items:
                   $ref: '#/components/schemas/FeedItem'
         '401':
-          description: Missing or invalid JWT
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+          $ref: '#/components/responses/Unauthorized'
         '500':
           description: Internal server error
           content:
@@ -840,11 +877,7 @@ paths:
                 items:
                   $ref: '#/components/schemas/FeedItem'
         '401':
-          description: Missing or invalid JWT
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+          $ref: '#/components/responses/Unauthorized'
         '500':
           description: Internal server error
           content:
@@ -1177,11 +1210,7 @@ paths:
                 offset: 0
                 total: 1
         '401':
-          description: Missing or invalid JWT
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+          $ref: '#/components/responses/Unauthorized'
         '500':
           description: Internal server error
           content:
@@ -1229,11 +1258,7 @@ paths:
                     error: Insufficient available balance
                     available: 1000000
         '401':
-          description: Missing or invalid JWT
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+          $ref: '#/components/responses/Unauthorized'
         '500':
           description: Internal server error
           content:
@@ -1281,11 +1306,7 @@ paths:
                     error: Insufficient earning balance
                     earning: 1000000
         '401':
-          description: Missing or invalid JWT
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+          $ref: '#/components/responses/Unauthorized'
         '500':
           description: Internal server error
           content:
@@ -1320,11 +1341,7 @@ paths:
                 auto_earn_enabled: true
                 message: "Auto-earn enabled. Idle stablecoins will be swept into the yield vault."
         '401':
-          description: Missing or invalid JWT
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
+          $ref: '#/components/responses/Unauthorized'
         '500':
           description: Internal server error
           content: