Consolidate Error Definitions in REST Spec

[jackye1995]

Apache Iceberg version

None

Query engine

None

Please describe the bug 🐞

Today, the error definitions are not consistent. There are in general 2 approaches, 4 subtypes:

Approach 1: inline definition

The definition is inline with the API definition:

        404:
          description: Not Found - Namespace provided in the `parent` query parameter is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'

The schema points to a generic IcebergErrorResponse, with examples of specific errors, typically mapping to Java exception types. The error examples are sometimes inline (1.1), sometimes pointing to the examples section (1.2).

Approach 2: specific error definition

The API error definition points to a schema:

        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'

and that schema points to the generic IcebergErrorResponse:

    ServiceUnavailableResponse:
      description:
        The service is not ready to handle the request. The client should wait and retry.


        The service may additionally send a Retry-After header to indicate when to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IcebergErrorResponse'
          example: {
            "error": {
              "message": "Slow down",
              "type": "SlowDownException",
              "code": 503
            }
          }

with examples of specific errors, typically mapping to Java exception types. The error examples are sometimes inline (2.1), sometimes pointing to the examples section (2.2).

We should make all these consistent. It seems like approach 2.2 is the right way to go and we can apply that to all the errors. It is also possible to use discriminator to define exact error models of specific error codes.