Spec: Add 404 response for config endpoint

[oguzhanunlu]

Summary

This PR proposes adding HTTP 404 as a documented response for the /v1/config endpoint in the REST Catalog OpenAPI specification.

Rationale

The /v1/config endpoint allows an optional query parameter for a warehouse identifier, e.g. /v1/config?warehouse=mywarehouse. But the openapi spec does not specify what should happen if the requested warehouse does not exist.

We noticed that Snowflake Open Catalog already returns a 404 for non-existent warehouses:

{
  "error": {
    "message": "Unable to find warehouse NONEXISTENT_WAREHOUSE_12345",
    "type": "NotFoundException",
    "code": 404
  }
}

This PR therefore formalizes what Snowflake Open Catalog is already doing in production. It seems sensible to formalize the 404 response code, because this is consistent with other Iceberg REST endpoints which allow a 404 response code for missing resources (tables, namespaces, views).

Our use case

At my company we triage Iceberg exceptions according to their type. For example, an exception for a missing resource might get triaged to the team responsible for providing that resource.

Currently, the Iceberg core library yields the generic RESTException if a warehouse does not exist. It is difficult to automatically triage the generic RESTException. It would help us if Iceberg could yield the NoSuchWarehouseException instead, so our application code can more confidently triage this runtime issue.

We expect other Iceberg users have similar operational workflows where distinguishing warehouse configuration errors from other failures would improve their incident response.

Context

Split from #14965 per @danielcweeks's suggestion to discuss and vote on the spec change separately from the implementation.

See the dev list thread: https://lists.apache.org/thread/07t5rfcxn3bbbpp75fkr2h1mwdp2o4mn

[kevinjqliu]

Thanks for re-opening this, the last one was lost in my email..
Throwing 404 here makes sense. Lets get this PR cleaned up and have just the rest spec changes.

Could you also start a thread on the iceberg devlist?
I've found a reference of past spec change discussion that you can use as a reference, https://lists.apache.org/thread/01gb9rygdd1gqks7lnl1o6440qocnh9m
You can just include your original PR's justification in the email.

[oguzhanunlu]

Thanks @kevinjqliu , I cleared the PR to have the spec change only and started a devlist thread at https://lists.apache.org/thread/07t5rfcxn3bbbpp75fkr2h1mwdp2o4mn with justification.

[kevinjqliu]

both PR and devlist thread mentions NotFoundException, should we change it to that?

[rambleraptor]

I'm personally a fan of not adding new response types.

We expect tools/libraries to be checking against the HTTP status codes when response parsing. But, if they're checking against the type, then those tools need to be updated to understand this new WarehouseNotFound exception.

[oguzhanunlu]

Thank you both for the feedback, let me share my view on both points.

@kevinjqliu That is an example from the Snowflake payload and I'd prefer NotFoundResponse to align with naming convention in the spec. However, I realized that 404 responses are inlined in all endpoints and named responses are used for status codes that mean the same thing across endpoints e.g. 400, 401, 403. It makes sense because what's not found is endpoint-dependent (namespace, table, view etc.) hence I think /v1/config 404 response should be inlined as well instead of adding e.g. NotFoundResponse. Would you agree?

@rambleraptor , @danielcweeks raised a valid concern in the original PR #14965: 404 from config endpoint is ambiguous. It could mean "warehouse not found" or "misconfigured URL pointing to a non-Iceberg server". If clients only check HTTP status code, they can't distinguish the two. How would you suggest handling that? e.g. PlanErrorHandler checks error type to decide which exception to throw.

Looking forward to hearing what you think.

[rdblue]

I agree with @danielcweeks that we need a way to distinguish what wasn't found, although I don't see why this doesn't just use our normal error response with an example. Here is one you can copy:

        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'  <--- Your error goes here

This doesn't require a new response object but does show how different missing objects can be represented.

I also wonder if this is the right response. Doesn't 404 typically mean that the resource identified by the path doesn't exist? But the config resource exists and the warehouse is just a parameter that the config resource is providing information for. I could be wrong, but I thought that 404 implied that the thing identified by the path doesn't exist, not that there was a problem finding information for a different (and optional) object.

[oguzhanunlu]

@rdblue Thanks for the feedback. I've pushed a new commit to follow the inline pattern you shared.

On status code choice, let me share that Apache Polaris throws NotFoundException which gets mapped to 404 when the warehouse doesn't exist.

[stevenzwu]

I also think 404 may not be the best fit, as it generally indicates that the endpoint itself could not be found. The endpoint receiving the query parameters does exist, and a lack of results is a valid outcome of the search/filter operation, not a client error in forming the request URI.

Maybe return 204 No Content as the request itself was valid and successfully processed.

[rambleraptor]

I don't think 204 is the proper way to go. The 4xx HTTP codes are meant to indicate client error. The client gave a warehouse that doesn't exist, which is a form of user error.

204 would mean that the warehouse exists and that the config has no parameters.