PRICE-2642 - Add 503 service unavailable details in DELETE price list and price records endpoints

reference/price_lists.v3.yml

@@ -481,6 +481,19 @@ paths:
                 properties: {}
                 additionalProperties: true
                 nullable: true
+        '503':
+          description: Service temporarily unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableError'
+              example:
+                error:
+                  code: SERVICE_DEGRADED
+                  message: Service temporarily unavailable
+                  details: "We're unable to process your request right now, please retry later"
+                  retry_after_seconds: 30
+                  timestamp: "2024-01-01T00:00:00.000Z"
   '/pricelists/{price_list_id}':
     parameters:
       - $ref: '#/components/parameters/Accept'
@@ -755,6 +768,19 @@ paths:
       responses:
         '204':
           description: Action has been enacted and no further information is to be supplied. `null` is returned.
+        '503':
+          description: Service temporarily unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableError'
+              example:
+                error:
+                  code: SERVICE_DEGRADED
+                  message: Service temporarily unavailable
+                  details: "We're unable to process your request right now, please retry later"
+                  retry_after_seconds: 30
+                  timestamp: "2024-01-01T00:00:00.000Z"
   '/pricelists/records':
     parameters:
       - $ref: '#/components/parameters/Accept'
@@ -1934,6 +1960,19 @@ paths:
                   instance:
                     type: string
                 description: No-content response for the BigCommerce API.
+        '503':
+          description: Service temporarily unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableError'
+              example:
+                error:
+                  code: SERVICE_DEGRADED
+                  message: Service temporarily unavailable
+                  details: "We're unable to process your request right now, please retry later"
+                  retry_after_seconds: 30
+                  timestamp: "2024-01-01T00:00:00.000Z"
   '/pricelists/{price_list_id}/records/{variant_id}':
     parameters:
       - $ref: '#/components/parameters/Accept'
@@ -2792,6 +2831,19 @@ paths:
         '204':
           description: ''
           content: {}
+        '503':
+          description: Service temporarily unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ServiceUnavailableError'
+              example:
+                error:
+                  code: SERVICE_DEGRADED
+                  message: Service temporarily unavailable
+                  details: "We're unable to process your request right now, please retry later"
+                  retry_after_seconds: 30
+                  timestamp: "2024-01-01T00:00:00.000Z"
   '/pricelists/assignments':
     parameters:
       - $ref: '#/components/parameters/Accept'
@@ -3339,6 +3391,36 @@ components:
       properties: {}
       additionalProperties: true
       description: Response metadata.
+    ServiceUnavailableError:
+      type: object
+      title: Service Unavailable Error
+      description: Returned when the service is temporarily unavailable.
+      properties:
+        error:
+          type: object
+          description: Top-level error wrapper.
+          properties:
+            code:
+              type: string
+              description: Error code identifying the type of failure.
+              example: SERVICE_DEGRADED
+            message:
+              type: string
+              description: Human-readable summary of the error.
+              example: Service temporarily unavailable
+            details:
+              type: string
+              description: Additional information about the error.
+              example: "We're unable to process your request right now, please retry later"
+            retry_after_seconds:
+              type: integer
+              description: Number of seconds to wait before retrying the request.
+              example: 30
+            timestamp:
+              type: string
+              format: date-time
+              description: ISO 8601 timestamp of when the error occurred.
+              example: "2024-01-01T00:00:00.000Z"
     ErrorResponse:
       allOf:
         - type: object