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 standardizes error handling across the Grid API by introducing a new GridError schema and enhancing flexibility in error responses.

Key Changes

New GridError schema: Created a reusable base error schema with code, message, and details fields at openapi/components/schemas/common/GridError.yaml
Flexible error details: Added additionalProperties: true to the details object in all HTTP error schemas (400, 401, 403, 404, 409, 412, 424, 500, 501), allowing APIs to include arbitrary metadata in error responses
Webhook error refactoring: Updated IncomingPaymentWebhookForbiddenResponse and IncomingPaymentWebhookUnprocessableResponse to extend from GridError instead of Error
Bulk import improvements: Created BulkCustomerImportErrorEntry schema that extends GridError and adds a correlationId field for tracking failed bulk import entries
Schema consolidation: Refactored BulkCustomerImportJob to reference the new BulkCustomerImportErrorEntry schema instead of defining error structure inline

Issues Found

Incomplete migration: openapi/paths/customers/customers_{customerId}.yaml:145 still references the old common/Error.yaml schema instead of the new GridError.yaml schema for the 410 response

Confidence Score: 4/5

This PR is mostly safe to merge but has one incomplete migration that should be addressed
The changes are well-structured and improve error handling standardization. However, the PR missed updating one reference from Error.yaml to GridError.yaml, creating an inconsistency. The old Error.yaml schema still exists and doesn't have additionalProperties: true, which means the 410 response won't benefit from flexible error details.
openapi/paths/customers/customers_{customerId}.yaml needs to be updated to complete the migration from Error to GridError

Important Files Changed

Filename	Overview
openapi/components/schemas/common/GridError.yaml	new standardized error schema with flexible `additionalProperties: true` on details object
openapi/components/schemas/customers/BulkCustomerImportErrorEntry.yaml	extends `GridError` and adds `correlationId` field for bulk import error tracking
openapi/components/schemas/webhooks/IncomingPaymentWebhookForbiddenResponse.yaml	updated to extend from `GridError` instead of `Error`
openapi/components/schemas/webhooks/IncomingPaymentWebhookUnprocessableResponse.yaml	updated to extend from `GridError` instead of `Error`

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as Grid API
    participant Validator
    participant ErrorHandler
    
    Client->>API: API Request
    API->>Validator: Validate Request
    
    alt Invalid Request
        Validator->>ErrorHandler: Validation Failed
        ErrorHandler->>ErrorHandler: Create GridError with<br/>code, message, details
        ErrorHandler->>API: Return Error4XX
        API->>Client: GridError Response<br/>(additionalProperties: true)
    else Server Error
        API->>ErrorHandler: Internal Error
        ErrorHandler->>ErrorHandler: Create GridError with<br/>code, message, details
        ErrorHandler->>API: Return Error5XX
        API->>Client: GridError Response<br/>(additionalProperties: true)
    else Webhook Response
        API->>Client: Webhook Event
        Client->>Client: Process Webhook
        alt Forbidden
            Client->>API: GridError with reason<br/>(e.g., RESTRICTED_JURISDICTION)
        else Unprocessable
            Client->>API: GridError with requiredFields<br/>(missing counterparty info)
        else Success
            Client->>API: 200 OK
        end
    else Bulk Import Error
        API->>ErrorHandler: Import Entry Failed
        ErrorHandler->>ErrorHandler: Create BulkCustomerImportErrorEntry<br/>(extends GridError + correlationId)
        ErrorHandler->>API: Add to errors array
        API->>Client: BulkCustomerImportJob with errors[]
    end

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

greptile-apps

_{4 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-28T04:36:14Z

Additional Comments (1)

openapi/paths/customers/customers_{customerId}.yaml
should reference GridError.yaml instead of Error.yaml to be consistent with 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:
should reference `GridError.yaml` instead of `Error.yaml` to be consistent with 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.

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