It seems reasonable to add the 404 response. I noticed that the warehouse
parameter is optional. I assume this is meant for catalog implementations
that support exactly one catalog or warehouse here so that client is OK to
skip it, though please correct me if I am mistaken. In that case, a 404
would still make sense when that single warehouse is not yet ready.
parameters:
- name: warehouse
in: query
required: false
Yufei
On Tue, Mar 24, 2026 at 8:33 AM Kevin Liu <[email protected]> wrote:
> Thanks for raising this proposal! I think it makes sense to add this to
> the spec and be explicit about the error case. I found the place where
> Apache Polaris throws `NotFoundException` for the `/v1/config` endpoint.
> The specific error `type` field can be used to disambiguate a route 404
> (URL doesn't exist) from a resource 404 (URL is valid, but the server
> cannot find the warehouse).
>
> Best,
> Kevin Liu
>
> [1]
> https://github.com/apache/polaris/blob/67daa9bb479eaa0ee6c4428984e253afc01b6efd/runtime/service/src/main/java/org/apache/polaris/service/catalog/iceberg/IcebergCatalogHandler.java#L1360
>
> On Tue, Mar 24, 2026 at 4:34 AM Oğuzhan Ünlü <[email protected]>
> wrote:
>
>> Hi everyone,
>>
>> I'd like to propose a small addition to the REST catalog spec:
>> documenting HTTP 404 as a valid response for the /v1/config endpoint when a
>> requested warehouse does not exist.
>>
>> The 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.
>>
>> 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 proposal 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).
>>
>> The Proposed Solution (PR-15746)
>>
>> Add a NoSuchWarehouseResponse to the OpenAPI spec for the /v1/config
>> endpoint, formalizing 404 as the response when a warehouse does not
>> exist. You can view the PR here:
>> https://github.com/apache/iceberg/pull/15746 .
>>
>> Looking forward to your thoughts.
>>
>> Best,
>> Oguzhan
>>
>
