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

pengying · 2026-01-24T22:52:56Z

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

pengying · 2026-01-24T22:53:09Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

This stack of pull requests is managed by Graphite. Learn more about stacking.

greptile-apps · 2026-01-24T22:58:04Z

Greptile Overview

Greptile Summary

This PR introduces a new GridError schema to standardize error responses across the API and adds flexibility to error details objects.

Key Changes

New GridError schema: Created a reusable error schema with code, message, and details fields, where details includes additionalProperties: true for flexible error information
Enhanced error flexibility: Added additionalProperties: true to the details field in all HTTP error schemas (400, 401, 403, 404, 409, 412, 424, 500, 501)
Webhook schema migration: Updated IncomingPaymentWebhookForbiddenResponse and IncomingPaymentWebhookUnprocessableResponse to extend GridError instead of Error
Bulk import refactoring: Created BulkCustomerImportErrorEntry schema that extends GridError and includes correlationId, simplifying the BulkCustomerImportJob.errors structure

Impact

The changes are backward-compatible in terms of response structure. The addition of additionalProperties: true allows the API to return additional error context without breaking existing clients, while the new GridError schema provides a cleaner foundation for future error responses.

Confidence Score: 5/5

This PR is safe to merge with no identified issues
The changes are well-structured schema improvements that enhance flexibility without breaking existing functionality. All error schemas consistently include additionalProperties, the new GridError schema follows OpenAPI best practices, and the refactoring simplifies the bulk import error structure while maintaining the same data model
No files require special attention

Important Files Changed

Filename	Overview
openapi/components/schemas/common/GridError.yaml	New `GridError` schema created with `code`, `message`, and `details` fields; includes `additionalProperties: true` for flexible error details
openapi/components/schemas/customers/BulkCustomerImportErrorEntry.yaml	New schema extending `GridError` to include `correlationId` for tracking failed bulk import entries
openapi/components/schemas/customers/BulkCustomerImportJob.yaml	Refactored to use `BulkCustomerImportErrorEntry` reference instead of inline nested error structure
openapi/components/schemas/webhooks/IncomingPaymentWebhookForbiddenResponse.yaml	Updated to extend `GridError` instead of `Error` for webhook forbidden responses
openapi/components/schemas/webhooks/IncomingPaymentWebhookUnprocessableResponse.yaml	Updated to extend `GridError` instead of `Error` for webhook unprocessable responses

Sequence Diagram

sequenceDiagram
    participant API as Grid API
    participant Schema as Error Schemas
    participant Client as API Client

    Note over API,Client: Error Response Flow

    Client->>API: API Request (e.g., POST /customers)
    
    alt Invalid Input (400)
        API->>Schema: Generate Error400
        Schema->>Schema: Include code, message, details (additionalProperties: true)
        Schema-->>API: Error Response
        API-->>Client: 400 Error Response
    end

    alt Webhook Error Handling
        API->>Schema: Generate GridError-based Response
        Note over Schema: IncomingPaymentWebhookForbiddenResponse<br/>or IncomingPaymentWebhookUnprocessableResponse
        Schema->>Schema: Extends GridError (code, message, details)
        Schema->>Schema: Add specific fields (reason/requiredFields)
        Schema-->>API: Webhook Error Response
        API-->>Client: Webhook Error Response
    end

    alt Bulk Import Errors
        API->>Schema: Generate BulkCustomerImportErrorEntry
        Schema->>Schema: Extends GridError (code, message, details)
        Schema->>Schema: Add correlationId
        Schema-->>API: Error Entry with correlationId
        API-->>Client: Bulk Import Job with errors array
    end

    Note over Schema: GridError provides base schema<br/>with flexible details object

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-27T01:33:27Z

Additional Comments (1)

openapi/paths/customers/customers_{customerId}.yaml
Incomplete migration: still references Error.yaml instead of GridError.yaml. For consistency with the rest of this PR, this should be updated to use GridError.yaml.

            $ref: ../../components/schemas/common/GridError.yaml

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/customers/customers_{customerId}.yaml
Line: 145:145

Comment:
Incomplete migration: still references `Error.yaml` instead of `GridError.yaml`. For consistency with the rest of this PR, this should be updated to use `GridError.yaml`.

```suggestion
            $ref: ../../components/schemas/common/GridError.yaml
```

How can I resolve this? If you propose a fix, please make it concise.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-27T05:22:59Z

Additional Comments (1)

openapi/paths/customers/customers_{customerId}.yaml
Inconsistent error schema reference - should use GridError.yaml instead of Error.yaml to match the PR's goal of standardizing on GridError

            $ref: ../../components/schemas/common/GridError.yaml

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/customers/customers_{customerId}.yaml
Line: 145:145

Comment:
Inconsistent error schema reference - should use `GridError.yaml` instead of `Error.yaml` to match the PR's goal of standardizing on `GridError`

```suggestion
            $ref: ../../components/schemas/common/GridError.yaml
```

How can I resolve this? If you propose a fix, please make it concise.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-27T05:28:37Z

Additional Comments (1)

openapi/paths/customers/customers_{customerId}.yaml
Update this to reference GridError for consistency with other error responses

            $ref: ../../components/schemas/common/GridError.yaml

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/customers/customers_{customerId}.yaml
Line: 145:145

Comment:
Update this to reference `GridError` for consistency with other error responses

```suggestion
            $ref: ../../components/schemas/common/GridError.yaml
```

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-27T20:42:48Z

Additional Comments (1)

openapi/paths/customers/customers_{customerId}.yaml
inconsistent reference - should use GridError instead of Error to match the pattern established in this PR

            $ref: ../../components/schemas/common/GridError.yaml

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/customers/customers_{customerId}.yaml
Line: 145:145

Comment:
inconsistent reference - should use `GridError` instead of `Error` to match the pattern established in this PR

```suggestion
            $ref: ../../components/schemas/common/GridError.yaml
```

How can I resolve this? If you propose a fix, please make it concise.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-27T21:24:17Z

Additional Comments (1)

openapi/paths/customers/customers_{customerId}.yaml
this should reference GridError.yaml not Error.yaml for consistency with the rest of the PR

            $ref: ../../components/schemas/common/GridError.yaml

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/customers/customers_{customerId}.yaml
Line: 145:145

Comment:
this should reference `GridError.yaml` not `Error.yaml` for consistency with the rest of the PR

```suggestion
            $ref: ../../components/schemas/common/GridError.yaml
```

How can I resolve this? If you propose a fix, please make it concise.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-28T00:01:08Z

Additional Comments (1)

openapi/paths/customers/customers_{customerId}.yaml
reference to Error.yaml should be updated to GridError.yaml for consistency

            $ref: ../../components/schemas/common/GridError.yaml

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/customers/customers_{customerId}.yaml
Line: 145:145

Comment:
reference to `Error.yaml` should be updated to `GridError.yaml` for consistency

```suggestion
            $ref: ../../components/schemas/common/GridError.yaml
```

How can I resolve this? If you propose a fix, please make it concise.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-28T00:11:51Z

Additional Comments (1)

openapi/paths/customers/customers_{customerId}.yaml
Still references old Error.yaml instead of GridError.yaml

            $ref: ../../components/schemas/common/GridError.yaml

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/paths/customers/customers_{customerId}.yaml
Line: 145:145

Comment:
Still references old `Error.yaml` instead of `GridError.yaml`

```suggestion
            $ref: ../../components/schemas/common/GridError.yaml
```

How can I resolve this? If you propose a fix, please make it concise.

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-28T00:19:09Z

Additional Comments (1)

openapi/components/schemas/common/Error.yaml
Error schema's details field is missing additionalProperties: true while all other error schemas now have it

  details:
    type: object
    description: Additional error details
    additionalProperties: true

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/components/schemas/common/Error.yaml
Line: 9:11

Comment:
`Error` schema's `details` field is missing `additionalProperties: true` while all other error schemas now have it

```suggestion
  details:
    type: object
    description: Additional error details
    additionalProperties: true
```

How can I resolve this? If you propose a fix, please make it concise.

… schemas

This was referenced Jan 24, 2026

feat: convert single-value enums to const for base types #126

Merged

feat: rename accounts to data in list external accounts response #127

Merged

pengying marked this pull request as ready for review January 24, 2026 22:55

pengying force-pushed the 01-24-feat_flatten_lightningexternalaccountinfo_schema_split_split_split_split branch from 6432728 to e5749d2 Compare January 27, 2026 01:29