feat: rename Error to GridError and add additionalProperties to error schemas (#131)

pengying · web-flow · commit c9ec7a2ba5ca · 2026-02-05T12:49:13.000-08:00
### TL;DR

Added a new `GridError` schema and improved error handling in the OpenAPI specification.

### What changed?

- Created a new `GridError` schema to standardize error responses
- Added `additionalProperties: true` to all error schema `details` objects to allow for flexible error details
- Refactored `BulkCustomerImportErrorEntry` to extend from `GridError` instead of using a nested error structure
- Updated webhook response schemas to reference `GridError` instead of `Error`
diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml
diff --git a/openapi.yaml b/openapi.yaml
diff --git a/openapi/components/schemas/common/GridError.yaml b/openapi/components/schemas/common/GridError.yaml
@@ -0,0 +1,13 @@
+type: object
+title: GridError
+properties:
+  code:
+    type: string
+    description: Error code
+  message:
+    type: string
+    description: Error message
+  details:
+    type: object
+    description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/customers/BulkCustomerImportErrorEntry.yaml b/openapi/components/schemas/customers/BulkCustomerImportErrorEntry.yaml
@@ -0,0 +1,11 @@
+allOf:
+  - $ref: ../common/GridError.yaml
+  - type: object
+    description: Error information for a failed bulk import entry
+    required:
+      - correlationId
+    properties:
+      correlationId:
+        type: string
+        description: Platform customer ID or row number for the failed entry
+        example: biz456
diff --git a/openapi/components/schemas/customers/BulkCustomerImportJob.yaml b/openapi/components/schemas/customers/BulkCustomerImportJob.yaml
@@ -45,17 +45,7 @@ properties:
     type: array
     description: Detailed error information for failed entries
     items:
-      type: object
-      required:
-        - correlationId
-        - error
-      properties:
-        correlationId:
-          type: string
-          description: Platform customer ID or row number for the failed entry
-          example: biz456
-        error:
-          $ref: ../common/Error.yaml
+      $ref: BulkCustomerImportErrorEntry.yaml
   completedAt:
     type: string
     format: date-time
diff --git a/openapi/components/schemas/errors/Error400.yaml b/openapi/components/schemas/errors/Error400.yaml
@@ -75,3 +75,4 @@ properties:
   details:
     type: object
     description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error401.yaml b/openapi/components/schemas/errors/Error401.yaml
@@ -25,3 +25,4 @@ properties:
   details:
     type: object
     description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error403.yaml b/openapi/components/schemas/errors/Error403.yaml
@@ -29,3 +29,4 @@ properties:
   details:
     type: object
     description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error404.yaml b/openapi/components/schemas/errors/Error404.yaml
@@ -37,3 +37,4 @@ properties:
   details:
     type: object
     description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error409.yaml b/openapi/components/schemas/errors/Error409.yaml
@@ -25,3 +25,4 @@ properties:
   details:
     type: object
     description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error410.yaml b/openapi/components/schemas/errors/Error410.yaml
@@ -0,0 +1,26 @@
+type: object
+required:
+  - message
+  - status
+  - code
+properties:
+  status:
+    type: integer
+    enum: 
+      - 410
+    description: HTTP status code
+  code:
+    type: string
+    description: |
+      | Error Code | Description |
+      |------------|-------------|
+      | CUSTOMER_DELETED | Customer has been permanently deleted |
+    enum:
+      - CUSTOMER_DELETED
+  message:
+    type: string
+    description: Error message
+  details:
+    type: object
+    description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error412.yaml b/openapi/components/schemas/errors/Error412.yaml
@@ -22,3 +22,4 @@ properties:
   details:
     type: object
     description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error424.yaml b/openapi/components/schemas/errors/Error424.yaml
@@ -29,3 +29,4 @@ properties:
   details:
     type: object
     description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error500.yaml b/openapi/components/schemas/errors/Error500.yaml
@@ -25,3 +25,4 @@ properties:
   details:
     type: object
     description: Additional error details
+    additionalProperties: true
diff --git a/openapi/components/schemas/errors/Error501.yaml b/openapi/components/schemas/errors/Error501.yaml
diff --git a/openapi/components/schemas/webhooks/IncomingPaymentWebhookForbiddenResponse.yaml b/openapi/components/schemas/webhooks/IncomingPaymentWebhookForbiddenResponse.yaml
diff --git a/openapi/components/schemas/webhooks/IncomingPaymentWebhookUnprocessableResponse.yaml b/openapi/components/schemas/webhooks/IncomingPaymentWebhookUnprocessableResponse.yaml
